Authentication

The Moqup API uses API keys for authentication. This guide covers how to create, use, and manage your API keys securely.

API Keys

Overview

API keys are the authentication method for the Moqup API:

• Simple to implement
• Workspace-scoped access
• Granular permission levels
• Support for multiple keys per workspace

Creating API Keys

1. Go to Settings > API > API Keys
2. Click Create New Key
3. Name your key (e.g., "CI/CD Integration")
4. Select permissions
5. Copy the key immediately

Using API Keys

Include in the Authorization header:

curl https://moqup.io/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Or use the X-API-Key header:

curl https://moqup.io/api/v1/projects \
  -H "X-API-Key: YOUR_API_KEY"

Key Format

All Moqup API keys start with the mq_ prefix:

mq_abc123xyz...

This makes it easy to identify Moqup keys in your configuration.

Permissions

Available Permissions

Permission Inheritance

• write permission includes read access
• admin permission includes all other permissions

Choosing Permissions

Follow the principle of least privilege:

Key Management

Managing Existing Keys

In your API settings, you can:

• View last used timestamp
• See key prefix for identification
• Revoke access instantly
• Create new keys as needed

Revoking Keys

To revoke a compromised or unused key:

1. Go to Settings > API > API Keys
2. Find the key by its name or prefix
3. Click Revoke
4. The key is immediately invalidated

Expiration

Keys can be set to expire:

• Never (default)
• Custom expiration date
• Expired keys are automatically rejected

Best Practices

Security

1. One key per integration: Easier to revoke if compromised
2. Minimum permissions: Only grant what's needed
3. Rotate regularly: Monthly or quarterly rotation recommended
4. Never commit to code: Use environment variables

Environment Variables

Store keys securely:

# .env.local (never commit this file)
MOQUP_API_KEY=mq_your_api_key_here

Use in your code:

const apiKey = process.env.MOQUP_API_KEY;

fetch('https://moqup.io/api/v1/projects', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

Server-Side Only

Never expose API keys in client-side code:

• Store in server environment
• Use in API routes
• Proxy requests through your backend

• Include in frontend bundles
• Store in localStorage
• Expose in client-side JavaScript

Error Handling

Authentication Errors

{
  "error": {
    "message": "Invalid API key.",
    "code": 401
  }
}

Common Errors

Handling Errors

async function apiRequest(endpoint) {
  const response = await fetch(`https://moqup.io/api/v1${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${process.env.MOQUP_API_KEY}`
    }
  });

  if (response.status === 401) {
    const error = await response.json();
    console.error('Authentication failed:', error.error.message);
    // Handle: check key, create new one, etc.
  }

  return response.json();
}

Rate Limiting

Limits by Plan

Authentication-related limits apply per API key:

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1678900000

Testing

Development Keys

Best practices for testing:

• Create separate keys for development
• Use read permission during testing
• Revoke test keys before production

Verifying Setup

Test your authentication:

curl -v https://moqup.io/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response returns your projects list.

Next Steps

1. Projects API - Start making requests
2. Files API - Upload and manage files
3. Rate Limits - Understand usage limits