API Key Authentication

API keys are the primary method for authenticating requests to the WeShape API. They allow you to securely access and manage your WeShape data programmatically.

Overview

The WeShape API uses API keys passed via HTTP headers to authenticate requests. Each API key is associated with your company account and inherits specific permissions that control what actions it can perform.

Using Your API Key

Authentication Header

Include your API key in the X-Api-Key header with every request:

curl https://v2.weshape.today/api/v3/archives \
  -H "X-Api-Key: wsk_live_your_api_key_here"

Code Examples

JavaScript/Node.js

const WESHAPE_API_KEY = process.env.WESHAPE_API_KEY;
const BASE_URL = 'https://v2.weshape.today/api';
 
async function getArchives() {
  const response = await fetch(`${BASE_URL}/v3/archives`, {
    method: 'GET',
    headers: {
      'X-Api-Key': WESHAPE_API_KEY,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }
  
  return await response.json();
}

Python

import os
import requests
 
WESHAPE_API_KEY = os.environ.get('WESHAPE_API_KEY')
BASE_URL = 'https://v2.weshape.today/api'
 
def get_archives():
    response = requests.get(
        f'{BASE_URL}/v3/archives',
        headers={
            'X-Api-Key': WESHAPE_API_KEY,
            'Content-Type': 'application/json'
        }
    )
    response.raise_for_status()
    return response.json()

cURL

curl -X GET https://v2.weshape.today/api/v3/archives \
  -H "X-Api-Key: wsk_live_your_api_key_here" \
  -H "Content-Type: application/json"

PHP

<?php
$apiKey = getenv('WESHAPE_API_KEY');
$baseUrl = 'https://v2.weshape.today/api';
 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/v3/archives');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
?>

Managing API Keys

List All API Keys

Retrieve all API keys for your company:

GET https://v2.weshape.today/api/auth/apikeys
X-Api-Key: your-existing-api-key

Response:

{
  "apiKeys": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "createdAt": "2026-01-15T10:00:00Z",
      "lastUsed": "2026-03-12T09:30:00Z"
    },
    {
      "id": "key_def456",
      "name": "Development Key",
      "createdAt": "2026-02-01T14:00:00Z",
      "lastUsed": "2026-03-10T16:45:00Z"
    }
  ]
}

Permissions

API keys can have different permission levels that control access to various resources. You can manage permissions for a specific API key through:

GET /v3/companies/{companyId}/api-keys/{keyId}/permissions
PUT /v3/companies/{companyId}/api-keys/{keyId}/permissions

Security Best Practices

1. Store Keys Securely

Never commit API keys to version control (use .gitignore)
Store keys in environment variables or secure credential management systems
Use different keys for development, staging, and production environments

# .env file (never commit this!)
WESHAPE_API_KEY=wsk_live_your_production_key
WESHAPE_API_KEY_DEV=wsk_test_your_development_key

2. Rotate Keys Regularly

Create new API keys periodically and revoke old ones to minimize security risks:

Create a new API key
Update your application to use the new key
Test thoroughly
Revoke the old key

3. Use Key-Specific Names

Give each API key a descriptive name indicating its purpose:

✅ “Production Server - Inventory Sync”
✅ “Mobile App - iOS”
❌ “Key 1”

4. Limit Key Permissions

Only grant the minimum permissions required for each key’s specific use case.

5. Monitor Key Usage

Regularly review API key usage and revoke any keys that are no longer needed or show suspicious activity.

Error Handling

Common Authentication Errors

Status Code	Error	Description	Solution
401	Unauthorized	Missing or invalid API key	Check that `X-Api-Key` header is included and correct
403	Forbidden	API key lacks required permissions	Verify key permissions include the necessary access
429	Too Many Requests	Rate limit exceeded	Implement exponential backoff and retry logic

Example Error Response

{
  "error": "Unauthorized",
  "errorMessage": "Invalid API key provided"
}

Error Handling Example

async function makeApiRequest(endpoint) {
  try {
    const response = await fetch(`${BASE_URL}${endpoint}`, {
      headers: { 'X-Api-Key': WESHAPE_API_KEY }
    });
    
    if (response.status === 401) {
      throw new Error('Invalid API key. Please check your credentials.');
    }
    
    if (response.status === 403) {
      throw new Error('Insufficient permissions. Contact your administrator.');
    }
    
    if (response.status === 429) {
      throw new Error('Rate limit exceeded. Please retry after some time.');
    }
    
    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Rate Limiting

API requests are subject to rate limiting to ensure fair usage. When you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Implement exponential backoff in your retry logic:

async function apiRequestWithRetry(endpoint, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(`${BASE_URL}${endpoint}`, {
        headers: { 'X-Api-Key': WESHAPE_API_KEY }
      });
      
      if (response.status === 429) {
        const waitTime = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Testing Your Integration

Quick Test

Test your API key with a simple request:

curl https://v2.weshape.today/api/v3/users/me/company \
  -H "X-Api-Key: wsk_live_your_api_key_here"

If successful, you’ll receive your company information, confirming your API key is working correctly.

Need Help?

If you encounter issues with API key authentication, please contact our support team at support@weshape.today.

Next Steps:

Introduction Users