Authentication

Get Your API Key

Go to switchport.ai and log in to your account.

Navigate to API Keys

Go to Settings → API Keys in the dashboard.

Copy your API key

Copy your API key. It should start with sp_.

Set Your API Key

There are two ways to authenticate with the Switchport API:

Option 1: Environment Variable (Recommended)

Set the SWITCHPORT_API_KEY environment variable:

export SWITCHPORT_API_KEY=sp_your_key_here

$env:SWITCHPORT_API_KEY="sp_your_key_here"

SWITCHPORT_API_KEY=sp_your_key_here

Then initialize the client with an empty string:

package main

import (
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	// Automatically reads from SWITCHPORT_API_KEY environment variable
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Use client...
}

Option 2: Pass API Key Directly

Pass the API key when creating the client:

package main

import (
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("sp_your_key_here")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Use client...
}

Never hard-code API keys in your source code. Use environment variables or a secrets management system instead.

Using .env Files

For local development, you can use a .env file with a library like godotenv:

Install godotenv:

go get github.com/joho/godotenv

Create a .env file in your project root:

SWITCHPORT_API_KEY=sp_your_key_here

Load the environment variables in your code:

package main

import (
	"log"

	"github.com/joho/godotenv"
	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	// Load .env file
	err := godotenv.Load()
	if err != nil {
		log.Println("Warning: .env file not found")
	}

	// Reads from environment
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Use client...
}

Add .env to your .gitignore file to avoid committing secrets to version control.

Configure API URL (Optional)

By default, the SDK connects to https://switchport-api.vercel.app. For local development or self-hosted instances, you can override this:

Using Environment Variable

export SWITCHPORT_API_URL=http://localhost:8001

The SDK will automatically read this environment variable.

Passing to Client

client, err := switchport.NewClient("sp_your_key_here")
if err != nil {
	log.Fatalf("Failed to create client: %v", err)
}

// Override the base URL
client.BaseURL = "http://localhost:8001"

Error Handling

If authentication fails, the SDK returns an AuthenticationError:

package main

import (
	"errors"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	response, err := client.Prompts.Execute("my-prompt", nil, nil)
	if err != nil {
		var authErr *switchport.AuthenticationError
		if errors.As(err, &authErr) {
			log.Printf("Authentication failed: %v", authErr)
			// Handle error (e.g., prompt user to check API key)
			return
		}
		log.Fatalf("Other error: %v", err)
	}

	log.Println(response.Text)
}

Common authentication errors:

Invalid API key: The API key is incorrect or has been revoked
Missing API key: No API key provided and SWITCHPORT_API_KEY is not set
Expired API key: The API key has expired (contact support)

API Key Validation

The SDK validates your API key format when creating the client:

client, err := switchport.NewClient("invalid_key")
if err != nil {
	// Error: API key must start with 'sp_'
	log.Printf("Validation error: %v", err)
}

API keys must:

Start with sp_
Be non-empty

Security Best Practices

Use environment variables

Store API keys in environment variables, not in source code.

Rotate keys regularly

Regularly rotate API keys to minimize risk if a key is compromised.

Use different keys for different environments

Use separate API keys for development, staging, and production.

Restrict key permissions

If available, use API keys with limited permissions for specific use cases.

Never commit secrets

Add .env and secrets files to .gitignore.

Use secrets management in production

In production, use proper secrets management solutions like AWS Secrets Manager, HashiCorp Vault, or Kubernetes secrets.

Next Steps

Execute Prompts

Learn how to execute prompts with the SDK

Getting Started

Core Features

Examples

Get Your API Key

Set Your API Key

Option 1: Environment Variable (Recommended)

Option 2: Pass API Key Directly

Using .env Files

Configure API URL (Optional)

Using Environment Variable

Passing to Client

Error Handling

API Key Validation

Security Best Practices

Next Steps

Execute Prompts

​Get Your API Key

​Set Your API Key

​Option 1: Environment Variable (Recommended)

​Option 2: Pass API Key Directly

​Using .env Files

​Configure API URL (Optional)

​Using Environment Variable

​Passing to Client

​Error Handling

​API Key Validation

​Security Best Practices

​Next Steps

Execute Prompts

Get Your API Key

Set Your API Key

Option 1: Environment Variable (Recommended)

Option 2: Pass API Key Directly

Using .env Files

Configure API URL (Optional)

Using Environment Variable

Passing to Client

Error Handling

API Key Validation

Security Best Practices

Next Steps