API Key Management

API keys provide programmatic access to the Neuramancer API. This guide covers API key management, rotation strategies, and best practices for maintaining secure, uninterrupted access to the API.

Overview

API keys are managed through dedicated endpoints at /v1/auth/api. Each tenant can have multiple API keys with different expiration dates, enabling sophisticated rotation strategies.

• Multiple keys per tenant: Support overlapping keys for zero-downtime rotation
• Mandatory expiration dates: All keys must have future expiry dates
• One-time secret visibility: Secrets shown only during creation
• UUID-based deletion: Delete keys by their unique identifier

Best Practices

• Regularly rotate API keys using overlapping expiration dates
• Use descriptive names for each key (e.g., “Production”, “Staging”, “CI/CD”)
• Set expiration dates to enforce key rotation

Viewing API Keys

Retrieve all API keys for your tenant. The response never includes secret values - only metadata.

Endpoint: GET /v1/auth/api?tenantName=<tenant_name>

API Key Format

API keys follow the format sk-<tenantTag>-<random> where:

• sk- prefix identifies it as a secret key
• <tenantTag> is the first 8 characters of base64url-encoded SHA256 hash of the tenant ID
• <random> is 24 bytes of base64url-encoded random data

Example: sk-a1b2c3d4-xYz9WaBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890

Secret Masking

API key secrets are returned in full only once in the POST /v1/auth/api creation response. Subsequent GET requests return masked secrets (*******).

Save the secret immediately when you create the key. There is no way to view it again.

Creating API Keys

Create a new API key for your tenant using POST /v1/auth/api. The secret is returned only once in the response.

Endpoint: POST /v1/auth/api

Response: 201 Created

Save Secret Immediately

The secret field contains the API key secret and is returned only once during creation. There is no way to retrieve it again. Save it immediately in a secure location.

Expiry Date Best Practices

• Production keys: 3-6 months
• Staging keys: 3-6 months
• Development keys: 1-3 months
• CI/CD keys: 2-4 weeks

Always create overlapping keys before the current key expires to ensure zero downtime.

Deleting API Keys

Delete an API key by its UUID.

Endpoint: DELETE /v1/auth/api?tenantName=<tenant_name>&uuid=<uuid>

UUID-Based Deletion

Each API key has a unique uuid field. To delete a key:

1. Call GET /v1/auth/api to list all keys
2. Identify the key to delete by its uuid or name
3. Use the uuid value as a query parameter in the DELETE request

Security Best Practices

Expiration Policies

Set expiration dates based on environment:

• Production: 3-6 months
• Test: Up to 12 months

Storage and Distribution

• Use secrets managers: AWS Secrets Manager, HashiCorp Vault, Azure Key Vault
• Never commit to version control: Add to .gitignore
• Encrypt at rest: Use encrypted environment variables
• Limit access: Only authorized personnel/systems
• Audit access: Log who retrieves keys and when

Compromise Response

If an API key is compromised:

0. Inform us immediately at [email protected]
1. Immediately deactivate the compromised key
2. Create a new key with different expiration
3. Update all systems to use new key
4. Audit usage logs for unauthorized access
5. Document incident for security review
6. Delete compromised key after migration

Least Privilege

• Limit key distribution to necessary systems only
• Consider using different tenants for isolated environments
• Monitor usage patterns for anomalies

Troubleshooting

Can’t View Key Secret

Cause: This is by design. Secrets are only visible on first retrieval.

Solution: Create a new key - there’s no way to view a masked secret again.