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

Log in to your WIIL console at https://console.wiil.io
Navigate to Settings → API Keys
Click Create New API Key
Give your key a descriptive name (e.g., "Production API", "Development")
Copy the generated API key immediately
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:

Environment	Key Name	Use Case
Development	`dev_api_key`	Local development and testing
Staging	`staging_api_key`	Pre-production testing
Production	`prod_api_key`	Live 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:

Create a new API key in the console
Update your application to use the new key
Test thoroughly in a non-production environment
Deploy the updated application
Revoke the old API key

Revoking Keys

If a key is compromised:

Immediately revoke it in the console (Settings → API Keys)
Create a new key
Update your applications
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

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

Rate Limiting

API keys are subject to rate limiting:

Tier	Requests per Minute
Standard	100
Professional	300
Enterprise	Custom

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

Issue	Symptom	Solution
Missing header	401 error	Add `X-WIIL-API-Key` header
Wrong header name	401 error	Use exact header name (case-insensitive)
Expired key	401 error	Generate new key in console
Wrong organization	403 error	Verify resource belongs to your org
Rate limit	429 error	Implement exponential backoff

Next Steps

Make your first API call in 5 minutes

Learn advanced API key management strategies

Additional Resources

API Reference - Complete API endpoint documentation
Guides - Integration and technical guides

Authentication

Overview

Obtaining an API Key

Through the Platform Console

Using Your API Key

Example Request

Authentication Header Format

Environment-Specific Keys

Setting Up Environment Variables

Node.js (.env file)

Python

Shell/Bash

Code Examples

JavaScript/TypeScript

Python

Go

Authentication Errors

401 Unauthorized

403 Forbidden

Managing API Keys

Rotating Keys

Revoking Keys

Multiple Keys

Security Best Practices

Rate Limiting

Testing Authentication

Test Your API Key

Common Integration Issues

Next Steps

⚡ Quick Start

🔑 API Keys Management

Additional Resources

Overview​

Obtaining an API Key​

Through the Platform Console​

Using Your API Key​

Example Request​

Authentication Header Format​

Environment-Specific Keys​

Setting Up Environment Variables​

Node.js (.env file)​

Python​

Shell/Bash​

Code Examples​

JavaScript/TypeScript​

Python​

Go​

Authentication Errors​

401 Unauthorized​

403 Forbidden​

Managing API Keys​

Rotating Keys​

Revoking Keys​

Multiple Keys​

Security Best Practices​

Rate Limiting​

Testing Authentication​

Test Your API Key​

Common Integration Issues​

Next Steps​

⚡ Quick Start

🔑 API Keys Management

Additional Resources​

Overview

Obtaining an API Key

Through the Platform Console

Using Your API Key

Example Request

Authentication Header Format

Environment-Specific Keys

Setting Up Environment Variables

Node.js (.env file)

Python

Shell/Bash

Code Examples

JavaScript/TypeScript

Python

Go

Authentication Errors

401 Unauthorized

403 Forbidden

Managing API Keys

Rotating Keys

Revoking Keys

Multiple Keys

Security Best Practices

Rate Limiting

Testing Authentication

Test Your API Key

Common Integration Issues

Next Steps

Additional Resources