Authentication

Overview

The Yachtsy Agent API uses API keys for authentication. Create, manage, and learn more about API keys in your account settings.

Remember that your API key is a secret! Do not share it with others or expose it in any client-side code (browsers, apps). API keys should be securely loaded from an environment variable or key management service on the server.

API keys should be provided via HTTP Bearer authentication:

Authorization: Bearer YACHTSY_API_KEY

Example Request

curl https://api.yachtsy.ai/v1/models \
  -H "Authorization: Bearer $YACHTSY_API_KEY"

Getting Your API Key

Method 1: Web Interface (Recommended)

1. Visit yachtsy.ai and create an account
2. Navigate to Settings → API Keys
3. Click Create New API Key
4. Give your key a descriptive name (e.g., "My Sailing App")
5. Copy and securely store your API key

Method 2: Development Environment

For local development, you can create API keys via the admin endpoint:

curl -X POST http://localhost:8000/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Key",
    "description": "Local testing key"
  }'

Using Your API Key

Environment Variables (Recommended)

Store your API key as an environment variable:

YACHTSY_API_KEY=your-api-key-here

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("YACHTSY_API_KEY"),
    base_url="https://api.yachtsy.ai/v1"
)

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: process.env.YACHTSY_API_KEY,
    baseURL: 'https://api.yachtsy.ai/v1'
});

Direct Usage

For testing purposes, you can use the API key directly:

from openai import OpenAI

client = OpenAI(
    api_key="yachtsy_12345...",  # Your actual API key
    base_url="https://api.yachtsy.ai/v1"
)

response = client.chat.completions.create(
    model="yachtsy-agent",
    messages=[{"role": "user", "content": "What's the best anchor for a 35ft sailboat?"}]
)

Authentication Headers

All API requests must include the Authorization header:

Authorization: Bearer your-yachtsy-api-key
Content-Type: application/json

API Key Management

Best Practices

• Rotate keys regularly for enhanced security
• Use different keys for different environments (dev, staging, production)
• Monitor usage through the Yachtsy dashboard
• Revoke compromised keys immediately

Key Permissions

API keys provide access to:

• Chat completions endpoint (/v1/chat/completions)
• Models information (/v1/models)
• Legacy completions (/v1/completions)

Error Responses

Common authentication errors:

Example error response:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Testing Your Setup

Verify your authentication is working:

curl -X GET https://api.yachtsy.ai/v1/models \
  -H "Authorization: Bearer your-yachtsy-api-key"

Expected response:

{
  "object": "list",
  "data": [
    {
      "id": "yachtsy-agent",
      "object": "model",
      "created": 1677610602,
      "owned_by": "yachtsy"
    }
  ]
}

Security Best Practices

Environment Variables

Always load your API key from environment variables, never hardcode it:

import os
from openai import OpenAI

# ✅ Good - Load from environment
client = OpenAI(
    base_url="https://api.yachtsy.ai/v1",
    api_key=os.getenv("YACHTSY_API_KEY")
)

# ❌ Bad - Hardcoded key
client = OpenAI(
    base_url="https://api.yachtsy.ai/v1", 
    api_key="yachtsy-12345..."  # Never do this!
)

Key Rotation

Regularly rotate your API keys for enhanced security:

1. Create a new API key
2. Update your applications to use the new key
3. Test that everything works correctly
4. Delete the old API key

Monitoring Usage

Monitor your API key usage in the Yachtsy dashboard to detect any unauthorized access.

Next Steps

Once authenticated, you can:

• Make your first API call
• Explore the API Reference for detailed endpoint documentation
• Check out Integration Guides for your specific framework
• Browse Examples for real-world use cases