Authentication

All API requests must be authenticated. Linkit supports two methods: Bearer tokens for user-scoped access and API keys for server-to-server communication.

Bearer Token

Authenticate with email and password to receive a token.

Obtain a Token

POST /api/v1/auth/login

Request

{
  "email": "user@example.com",
  "password": "your_password"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-16T10:30:00Z",
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "organization_id": "org_123"
  }
}

Using Bearer Tokens

Include the token in the Authorization header:

curl -X GET "https://linkit.works/api/v1/products" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key

API keys are generated from the admin dashboard and don't expire unless revoked. They are better suited for automated workflows and server-to-server integrations.

Using API Keys

Pass the key directly in the Authorization header:

curl -X GET "https://linkit.works/api/v1/products" \
  -H "Authorization: your_api_key_here"

Organization Header

Some endpoints require an organization context. If your token is not already scoped to an organization, include the header:

X-Organization-ID: org_123

This is typically needed when a user belongs to multiple organizations.

Example Requests

# Bearer token
curl -X GET "https://linkit.works/api/v1/products" \
  -H "Authorization: Bearer your_token_here"

# API key
curl -X GET "https://linkit.works/api/v1/products" \
  -H "Authorization: your_api_key_here"

# With organization header
curl -X GET "https://linkit.works/api/v1/products" \
  -H "Authorization: Bearer your_token_here" \
  -H "X-Organization-ID: org_123"

// Bearer token
const response = await fetch('https://linkit.works/api/v1/products', {
  headers: {
    'Authorization': 'Bearer your_token_here'
  }
});

// API key with organization
const response = await fetch('https://linkit.works/api/v1/products', {
  headers: {
    'Authorization': 'your_api_key_here',
    'X-Organization-ID': 'org_123'
  }
});

import requests

# Bearer token
response = requests.get(
    'https://linkit.works/api/v1/products',
    headers={'Authorization': 'Bearer your_token_here'}
)

# API key with organization
response = requests.get(
    'https://linkit.works/api/v1/products',
    headers={
        'Authorization': 'your_api_key_here',
        'X-Organization-ID': 'org_123'
    }
)

Error Responses

401 Unauthorized

Returned when credentials are missing or invalid:

{
  "code": 401,
  "error": "Unauthorized",
  "details": "Invalid or expired token"
}

403 Forbidden

Returned when credentials are valid but lack permission for the requested resource:

{
  "code": 403,
  "error": "Forbidden",
  "details": "Insufficient permissions for this organization"
}

Security Best Practices

• Store tokens and API keys in environment variables, not in source code.
• Use HTTPS exclusively — the API rejects plain HTTP.
• Rotate API keys periodically. Revoke any key you suspect has been compromised.
• Use Bearer tokens for short-lived user sessions and API keys for long-lived service accounts.
• Scope tokens to the minimum required organization access.

Next Steps