Authentication

This guide covers everything you need to know about authenticating with the Neuramancer API for B2B integrations.

Overview

The Neuramancer API uses API Key authentication for all programmatic access.

API keys provide:

• Secure, token-based authentication
• Tenant-scoped access control
• Mandatory expiration dates
• Simple integration for automated systems

Authentication vs Authorization

Authentication identifies your system:

• Proves your identity to the API via API key
• Required for all protected endpoints

Authorization determines what you can access:

• Validates access to specific tenant resources
• Automatically scoped to your API key’s tenant
• API keys provide standard access to all API features for the tenant

Authentication Flow

The API validates API keys on every request:

sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: Request with API Key
    Note over Client,API: Authorization: ApiKey sk-...
    
    API->>Database: Lookup tenant by API key
    Database-->>API: Tenant found
    
    API->>API: Validate key expiry
    
    alt Key valid && not expired
        API-->>Client: 200 OK + Response
    else Key expired
        API-->>Client: 401 Unauthorized
    else Key not found or access denied
        API-->>Client: 403 Forbidden
    end

Status Code 401 vs 403

• 401 Unauthorized: Returned when authentication credentials are provided but invalid (expired API key)
• 403 Forbidden: Returned when no credentials are provided for a protected endpoint or the permissions are insufficient (API service keys cannot access every protected endpoint)

---

API Key Authentication

What Are API Keys?

API keys are secret tokens that identify your tenant and provide programmatic access to the API.

They:

• Are scoped to a specific tenant
• Allow for standard API feature access (no granular permissions)
• Expire after a defined period for security
• Are only shared once at creation time - we store the HMAC hash securely
• Can be rotated regularly for security best practices using our API Key Management features
• Start with sk- prefix (“sk” stands for “service key”)
• Can be used by multiple systems simultaneously

Format: sk-<tenantTag>-<random>

Example: sk-a1b2c3d4-xYz9WaBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890

Obtaining and Revoking API Keys

The initial API key must be created by a Neuramancer administrator with access to your tenant - please contact your internal Neuramancer admin or support.

If you have a valid API key, new API keys can be created, existing API keys listed, and revoked programmatically via the API Key Management API.

One-Time Retrieval

API key secrets cannot be retrieved after creation. If lost, you must create a new key.

Using API Keys

Any request to a protected endpoint must include the API key for authentication in the Authorization header.

Authorization: ApiKey sk-aaaabbbb-xYz9WaBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890

---

Webhook Credential & Secret Rotation

Beyond rotating API keys, you should also periodically rotate webhook authentication tokens and blob storage credentials. Both can be updated via the Tenant Management API (PUT /v1/tenant) - either directly through the REST API or using the SDK scripts:

Python SDK - update_tenant.py

PHP SDK - update_tenant.php

Rotating Webhook Tokens

If your webhook is secured with a presigned URL (e.g. a query-parameter token or a secret path segment), you should rotate that token regularly. Because the token is embedded in the URL itself, rotation means updating the webhookUrl on your tenant.

sequenceDiagram
    participant Ops as Your Ops / CI
    participant App as Your Application
    participant API as Neuramancer API
    participant WH as Your Webhook Endpoint

    Note over Ops: 1. Generate new token / new pre-signed URL
    Ops->>App: Deploy webhook endpoint<br/>with new token/new presigned URL
    Note over App: Endpoint now accepts<br/>both old & new tokens / presigned URLs during transition

    Ops->>API: PUT /v1/tenant<br/>{ "webhookUrl": "https://new_webhook_url_with_rotated_token" }
    API-->>Ops: 200 OK - tenant updated

    Note over API,WH: All subsequent webhook calls use new URL

    API->>WH: POST https://new_webhook_url_with_rotated_token<br/>(analysis status change)
    WH-->>API: 200 OK

    Ops->>App: Remove old token / presigned URL from allow-list
    Note over App: Only new token / presigned URL accepted - repeat the process with next rotation

1. Generate a new token / new pre-signed URL in your secrets manager or CI pipeline.

2. Deploy your webhook endpoint so it accepts both the old and new tokens / pre-signed URLs during the transition window.

3. Update the tenant with the new presigned webhook URL:

   # Using the Python SDK
   python update_tenant.py webhookUrl="https://example.com/webhooks/neuramancer?token=NEW_TOKEN"
   
   # Using the PHP SDK
   php update_tenant.php webhookUrl="https://example.com/webhooks/neuramancer?token=NEW_TOKEN"
   
   # Using cURL directly
   curl -X PUT "https://api.neuramancer.dev/v1/tenant?tenantName=demo" \
     -H "Authorization: ApiKey sk-..." \
     -H "Content-Type: application/json" \
     -d '{"webhookUrl":"https://example.com/webhooks/neuramancer?token=NEW_TOKEN"}'

4. Remove the old token / presigned URL from your endpoint’s allow-list once you have confirmed the new token is active.

Zero-Downtime Rotation

By temporarily accepting both tokens / presigned URLs in step 2, you avoid dropping any webhook deliveries during rotation.

Rotating Blob Storage Credentials

If you use a custom S3-compatible storage endpoint, your access key and secret key should be rotated according to your organisation’s security policy. The process is the same - update the tenant’s storage configuration via PUT /v1/tenant.

See Blob Storage Management for the full list of S3 configuration fields, and the PHP SDK or Python SDK for the corresponding environment variables.

# Using the Python SDK (reads S3 credentials from .env)
python update_tenant.py --s3-from-env

# Using the PHP SDK
php update_tenant.php --s3-from-env

Danger - Full Overwrite

PUT /v1/tenant overwrites existing tenant settings. Always ensure your .env file or request body contains all required storage fields - not just the rotated credentials - to avoid clearing existing configuration. See the Blob Storage Management reference for the full schema.

---

Troubleshooting

401 Unauthorized

Meaning: API key is invalid or expired.

Causes:

• API key expired (check expiry date)
• Invalid API key format
• Incorrect API key value

Solutions:

• Contact your administrator or support to check the API key expiry date
• Verify you’re using the complete API key (starts with sk-)
• Ensure no extra whitespace or line breaks in the key
• Request a new API key if expired

403 Forbidden

Meaning: No authentication provided or insufficient permissions.

Causes:

• Missing Authorization header
• Request to protected endpoint without credentials (service key permissions not sufficient)
• API key does not belong to the tenant

Solution:

Ensure you include the Authorization header:

curl -H "Authorization: ApiKey sk-..." \
  https://api.neuramancer.dev/v1/analysis?tenantName=demo

Debug Checklist

When authentication fails, check the following:

• Credentials present? Authorization header included?
• Correct format? Authorization: ApiKey sk-... or Authorization: Bearer sk-...
• Not expired? Check API key expiry date with your administrator
• Correct tenant? Verify tenant name matches your API key’s tenant
• HTTPS? API only accepts HTTPS connections
• Valid endpoint? Check endpoint exists and HTTP method is correct

Debugging commands:

Please note:

• Replace sk-... with your actual API key.
• Replace the endpoint URL with the one you’re testing against.
• Replace the tenant name as needed.

# Test with verbose output
curl -v -H "Authorization: ApiKey sk-..." \
  https://api.neuramancer.dev/v1/analysis?tenantName=demo

# Check HTTP status code
curl -w "%{http_code}" -H "Authorization: ApiKey sk-..." \
  https://api.neuramancer.dev/v1/analysis?tenantName=demo

# View response headers
curl -I -H "Authorization: ApiKey sk-..." \
  https://api.neuramancer.dev/v1/analysis?tenantName=demo

Unauthenticated Endpoints

The following endpoints do not require authentication:

• /v1/health - Health check
• /v1/ping - Connectivity test
• /v1/schema - OpenAPI schema

All other endpoints require API key authentication.

Support

Should you need further assistance, please contact our support team at [email protected]