Skip to main content

Authentication

The WIIL API uses API keys for authentication. This guide covers everything you need to know about obtaining, using, and managing your API keys.

Overview​

All API requests must include a valid API key in the request headers. API keys:

  • Are unique to your organization
  • Can be revoked at any time
  • Should be kept secure and never exposed publicly
  • Provide full access to your organization's resources

Obtaining an API Key​

Through the Platform Console​

  1. Log in to your WIIL console at https://console.wiil.io
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Give your key a descriptive name (e.g., "Production API", "Development")
  5. Copy the generated API key immediately
  6. Store it securely (you won't be able to see it again)
Security Best Practice
  • Never commit API keys to version control
  • Don't expose API keys in client-side code
  • Use environment variables to store API keys
  • Rotate keys regularly for enhanced security

Using Your API Key​

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

Example Request​

curl -X GET "https://api.wiil.io/v1/organizations" \
  -H "X-Wiil-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Authentication Header Format​

X-Wiil-Api-Key: your_api_key_here

Alternative header name (case-insensitive):

X-Wiil-Api-Key: your_api_key_here

Environment-Specific Keys​

We recommend using different API keys for different environments:

EnvironmentKey NameUse Case
Developmentdev_api_keyLocal development and testing
Stagingstaging_api_keyPre-production testing
Productionprod_api_keyLive production applications

Setting Up Environment Variables​

Node.js (.env file)​

WIIL_API_KEY=your_api_key_here
WIIL_API_BASE_URL=https://api.wiil.io/v1
require('dotenv').config();

const apiKey = process.env.WIIL_API_KEY;
const baseUrl = process.env.WIIL_API_BASE_URL;

Python​

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('WIIL_API_KEY')
base_url = os.getenv('WIIL_API_BASE_URL')

Shell/Bash​

export WIIL_API_KEY="your_api_key_here"
export WIIL_API_BASE_URL="https://api.wiil.io/v1"

Code Examples​

JavaScript/TypeScript​

const WIIL_API_KEY = process.env.WIIL_API_KEY;
const BASE_URL = 'https://api.wiil.io/v1';

async function makeAuthenticatedRequest(endpoint: string) {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'GET',
    headers: {
      'X-Wiil-Api-Key': WIIL_API_KEY,
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return response.json();
}

// Usage
const organization = await makeAuthenticatedRequest('/organizations');

Python​

import requests
import os

API_KEY = os.getenv('WIIL_API_KEY')
BASE_URL = 'https://api.wiil.io/v1'

def make_authenticated_request(endpoint):
    headers = {
        'X-Wiil-Api-Key': API_KEY,
        'Content-Type': 'application/json',
    }

    response = requests.get(f'{BASE_URL}{endpoint}', headers=headers)
    response.raise_for_status()

    return response.json()

# Usage
organization = make_authenticated_request('/organizations')

Go​

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

const baseURL = "https://api.wiil.io/v1"

func makeAuthenticatedRequest(endpoint string) (map[string]interface{}, error) {
    apiKey := os.Getenv("WIIL_API_KEY")

    req, err := http.NewRequest("GET", baseURL+endpoint, nil)
    if err != nil {
        return nil, err
    }

    req.Header.Set("X-Wiil-Api-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

    var result map[string]interface{}
    err = json.Unmarshal(body, &result)

    return result, err
}

func main() {
    org, err := makeAuthenticatedRequest("/organizations")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    fmt.Println(org)
}

Authentication Errors​

401 Unauthorized​

Occurs when the API key is missing or invalid.

Response:

{
  "success": false,
  "data": null,
  "error": "Unauthorized - Authentication required",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common causes:

  • Missing X-Wiil-Api-Key header
  • Invalid or expired API key
  • Typo in the header name

Solution:

  • Verify the API key is correctly set
  • Check the header name spelling
  • Ensure the key hasn't been revoked

403 Forbidden​

Occurs when authentication succeeds but you lack permission for the requested resource.

Response:

{
  "success": false,
  "data": null,
  "error": "Forbidden - Not authorized to access this resource",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common causes:

  • Attempting to access resources from a different organization
  • Insufficient permissions for the operation

Solution:

  • Verify you're accessing resources within your organization
  • Contact support if you believe you should have access

Managing API Keys​

Rotating Keys​

For security, rotate your API keys regularly:

  1. Create a new API key in the console
  2. Update your application to use the new key
  3. Test thoroughly in a non-production environment
  4. Deploy the updated application
  5. Revoke the old API key

Revoking Keys​

If a key is compromised:

  1. Immediately revoke it in the console (Settings → API Keys)
  2. Create a new key
  3. Update your applications
  4. Monitor for any unauthorized access attempts

Multiple Keys​

You can create multiple API keys for:

  • Different applications
  • Different team members
  • Different environments
  • Granular access control

Security Best Practices​

  1. Use Environment Variables: Never hardcode API keys
  2. Limit Key Scope: Use different keys for different purposes
  3. Regular Rotation: Rotate keys every 90 days
  4. Monitor Usage: Review API logs regularly
  5. Immediate Revocation: Revoke compromised keys immediately
  6. Secure Storage: Use secure secret management systems in production (e.g., AWS Secrets Manager, HashiCorp Vault)
  7. HTTPS Only: Always use HTTPS for API requests
  8. Least Privilege: Grant only the minimum required permissions
  9. Audit Logs: Enable and review audit logs regularly
  10. Secret Scanning: Use tools to detect accidentally committed secrets

Rate Limiting​

API keys are subject to rate limiting:

TierRequests per Minute
Standard100
Professional300
EnterpriseCustom

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "data": null,
  "error": "Rate limit exceeded. Please retry after 60 seconds.",
  "retry_after": 60,
  "timestamp": "2024-01-15T10:30:00Z"
}

See the Guides for detailed strategies and best practices.

Testing Authentication​

Test Your API Key​

Use this simple request to verify your API key is working:

curl -X GET "https://api.wiil.io/v1/organizations" \
  -H "X-Wiil-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Expected successful response:

{
  "success": true,
  "data": {
    "id": "org_123456",
    "name": "Your Organization",
    "createdAt": 1704067200000
  },
  "metadata": {
    "timestamp": 1704067200000,
    "version": "v1"
  }
}

Common Integration Issues​

IssueSymptomSolution
Missing header401 errorAdd X-Wiil-Api-Key header
Wrong header name401 errorUse exact header name (case-insensitive)
Expired key401 errorGenerate new key in console
Wrong organization403 errorVerify resource belongs to your org
Rate limit429 errorImplement exponential backoff

Next Steps​

⚡ Quick Start

Make your first API call in 5 minutes

Start Now

🔑 API Keys Management

Learn advanced API key management strategies

Learn More

Additional Resources​