Skip to main content
All API requests require authentication using an API key in the Authorization header.

​
API Keys

Send your API key using the Bearer authentication scheme: 
Authorization: Bearer YOUR_API_KEY

​
Getting Your API Key

  1. Sign up at signa.so/dashboard
  2. Navigate to the API Keys section
  3. Click “Generate New API Key”
  4. Copy and store it securely
Your API key will look like: tm_live_abc123xyz...
Keep your API keys secure!
  • Never commit them to version control
  • Don’t expose them in client-side code
  • Rotate keys regularly
  • Use environment variables

​
Example Requests

curl https://api.signa.so/v1/trademarks/search?q=apple \
  -H "Authorization: Bearer tm_live_abc123xyz..."

​
Key Management

​
Environment Variables

Store your API key as an environment variable: 
# .env file (add to .gitignore!)
TRADEMARK_API_KEY=tm_live_abc123xyz...
Then use it in your code: 
const apiKey = process.env.TRADEMARK_API_KEY;

​
Multiple Environments

Create separate keys for different environments:
  • Development: tm_test_...
  • Staging: tm_test_...
  • Production: tm_live_...
Test keys have limited functionality and don’t consume credits.

​
Key Rotation

Rotate keys regularly for security:
  1. Generate a new key in the dashboard
  2. Update your application with the new key
  3. Test the new key works
  4. Revoke the old key
Zero-downtime rotation:
  • Use both old and new keys temporarily
  • Gradually migrate to the new key
  • Revoke the old key once fully migrated

​
Revoking Keys

Immediately revoke a key if:
  • It’s been exposed publicly
  • An employee with access leaves
  • You suspect unauthorized access
Revoked keys return 401 Unauthorized immediately.

​
API Key Scopes

Keys can have different permission scopes:
ScopeDescriptionUse Case
Full AccessAll API operationsProduction applications
Read OnlySearch and lookup onlyAnalytics dashboards
LimitedSpecific endpoints onlyThird-party integrations
Set scopes in the dashboard when creating keys.

​
Error Responses

​
Missing API Key

{
  "error": {
    "code": "unauthorized",
    "message": "No API key provided",
    "request_id": "req_abc123xyz"
  }
}

​
Invalid API Key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "request_id": "req_abc123xyz"
  }
}

​
Expired API Key

{
  "error": {
    "code": "api_key_expired",
    "message": "API key expired. Please generate a new key.",
    "request_id": "req_abc123xyz"
  }
}

​
Revoked API Key

{
  "error": {
    "code": "unauthorized",
    "message": "API key has been revoked",
    "request_id": "req_abc123xyz"
  }
}

​
Best Practices

Never hardcode API keys in your source code:
// Bad
const apiKey = 'tm_live_abc123...';

// Good
const apiKey = process.env.TRADEMARK_API_KEY;
Validate API keys before making requests:
function validateApiKey(key) {
  if (!key) {
    throw new Error('API key is required');
  }
  if (!key.startsWith('tm_')) {
    throw new Error('Invalid API key format');
  }
  return true;
}
Provide clear error messages for authentication failures:
if (error.code === 'unauthorized') {
  console.error('Authentication failed. Please check your API key.');
  // Notify user/admin
}
Track which keys are used where:
const response = await fetch(url, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-App-Version': '1.2.3',
    'X-Environment': 'production'
  }
});
View key usage analytics in your dashboard.

​
Security Recommendations

Important Security Practices:
  1. Never commit API keys to Git
  2. Never log API keys (even partially)
  3. Never send keys in URL parameters
  4. Always use HTTPS
  5. Always validate requests server-side
  6. Rotate keys every 90 days
  7. Monitor for unusual activity
  8. Use separate keys per application

​
Client-Side vs Server-Side

API keys should be used server-side: 
// Node.js server
app.get('/api/search', async (req, res) => {
  const response = await fetch(
    `https://api.signa.so/v1/trademarks/search?q=${req.query.q}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TRADEMARK_API_KEY}`
      }
    }
  );
  const data = await response.json();
  res.json(data);
});
Don’t expose API keys in browser JavaScript: 
// Bad - API key exposed in browser
const response = await fetch('https://api.signa.so/v1/trademarks/search?q=apple', {
  headers: {
    'Authorization': `Bearer tm_live_abc123...` // Visible in DevTools!
  }
});
If you must use client-side, use a proxy server.

​
Webhook Authentication

For webhooks, we sign requests with your webhook secret: 
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/trademarks', (req, res) => {
  const signature = req.headers['x-trademark-signature'];

  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});
See Webhooks Guide for more details.

​
FAQ

Yes, but we recommend using separate keys for each application. This makes it easier to track usage and rotate keys without affecting other apps.
Keys don’t expire automatically, but you can set expiration dates in the dashboard. We recommend rotating keys every 90 days.
Immediately revoke it in the dashboard and generate a new one. Monitor your usage to check for unauthorized access.
No. Once revoked, a key cannot be recovered. You must generate a new key.
Unlimited. Create as many keys as needed for different applications and environments.

​
Next Steps

Quickstart Guide

Make your first API request

Rate Limits

Understand credit usage