Authentication

Learn how to authenticate with the Sharokey API using our official SDKs.

🔑 Overview

All Sharokey API operations require authentication using API tokens. Our SDKs handle all authentication automatically once configured.

Official SDKs:

• CLI C# Tool - Cross-platform command-line interface
• JavaScript SDK - For Node.js and modern web applications
• JavaScript CDN - Simple browser integration
• Python SDK - Async Python client

🚀 Getting Your Token

1. Sign up for a Sharokey account at sharokey.com
2. Access your dashboard → Settings → API Tokens
3. Create a new token with appropriate scopes
4. Copy your token and configure it in your SDK

⚙️ Token Configuration

Configure your API token using the appropriate method for your client:

CLI C#

sharokey config --token YOUR_API_TOKEN

JavaScript SDK

const client = new SharokeyClient({
  token: 'YOUR_API_TOKEN'
});

JavaScript CDN

Sharokey.config({
  token: 'YOUR_API_TOKEN'
});

Python SDK

client = sharokey.SharokeyClient(token='YOUR_API_TOKEN')

🔐 Environment Variables

For security, use environment variables instead of hardcoding tokens:

CLI C#

export SHAROKEY_TOKEN="YOUR_API_TOKEN"
sharokey config --token $SHAROKEY_TOKEN

JavaScript SDK

const client = new SharokeyClient({
  token: process.env.SHAROKEY_TOKEN
});

JavaScript CDN

// Not recommended for client-side use
// Use server-side proxy instead

Python SDK

import os
client = sharokey.SharokeyClient(token=os.environ['SHAROKEY_TOKEN'])

🛡️ Security Best Practices

Token Storage

Never Expose Tokens

• Don't commit tokens to version control
• Don't log tokens in application logs
• Don't expose tokens in client-side code
• Don't share tokens via insecure channels

SDK Security Features

• Automatic encryption: CLI encrypts and stores tokens securely
• Environment support: All SDKs support environment variables
• Token validation: Automatic validation before API calls
• Error handling: Structured authentication error responses

🚨 Authentication Errors

All SDKs handle authentication errors automatically and provide structured error objects.

Invalid Token

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Token is invalid or expired"
  }
}

Missing Token

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "API token is required"
  }
}

Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions for this operation"
  }
}

🔧 SDK Authentication Features

Automatic Handling

• Token management: SDKs store and manage tokens securely
• Request authentication: Automatic inclusion of auth headers
• Error detection: Immediate feedback on authentication issues
• Token validation: Pre-request validation to avoid failed calls

Configuration Options

• Environment variables: SHAROKEY_TOKEN
• Configuration files: Secure encrypted storage (CLI)
• Constructor parameters: Direct token passing
• Runtime configuration: Update tokens dynamically

✅ Verification

Test your authentication setup:

CLI C#

sharokey test-auth

JavaScript SDK

const isValid = await client.testAuthentication();
console.log(isValid ? 'Auth OK' : 'Auth Failed');

JavaScript CDN

const isValid = await Sharokey.testAuth();
console.log(isValid ? 'Auth OK' : 'Auth Failed');

Python SDK

is_valid = await client.test_authentication()
print("Auth OK" if is_valid else "Auth Failed")

🔗 Next Steps

• CLI Documentation - Command-line interface setup
• JavaScript SDK - JavaScript/Node.js integration
• Python SDK - Python integration
• Secrets API - Create and manage secrets
• Error Handling - Complete error reference