Authentication

SolCognia API uses API keys for authentication, with optional OAuth 2.0 support for user-facing applications.

API Key Authentication

Getting Your API Key

1. Register at solcognia.xyz

2. Navigate to Developer Dashboard

3. Click "Generate API Key"

4. Copy and securely store your key

Using API Keys

Include your API key in the Authorization header:

curl -H "Authorization: Bearer sk_live_1234567890abcdef" \
     https://api.solcognia.xyz/v1/models

API Key Types

Development Keys (sk_dev_...)

• Limited to 100 requests per hour

• Access to basic AI models only

• Suitable for testing and development

Production Keys (sk_live_...)

• Higher rate limits based on your plan

• Access to all available features

• Required for production applications

OAuth 2.0 (Coming Soon)

For applications that need to act on behalf of users:

Authorization Flow

1. Authorization Request

https://auth.solcognia.xyz/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  scope=read_profile+manage_workflows&
  redirect_uri=YOUR_REDIRECT_URI

1. Token Exchange

curl -X POST https://auth.solcognia.xyz/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&
      code=AUTHORIZATION_CODE&
      client_id=YOUR_CLIENT_ID&
      client_secret=YOUR_CLIENT_SECRET"

1. Using Access Tokens

curl -H "Authorization: Bearer ACCESS_TOKEN" \
     https://api.solcognia.xyz/v1/user/profile

Wallet-Based Authentication

For blockchain-specific operations:

Wallet Connection

import { SolCogniaSDK } from '@solcognia/sdk';

const sdk = new SolCogniaSDK({
  apiKey: 'your-api-key',
  walletAdapter: phantomWallet // or other Solana wallet
});

await sdk.connectWallet();

Signed Requests

Some operations require wallet signatures for security:

const result = await sdk.claimTokens({
  amount: 100,
  signature: await wallet.signMessage(message)
});

Security Best Practices

API Key Management

• Never expose API keys in client-side code

• Use environment variables for key storage

• Rotate keys regularly

• Use different keys for different environments

Rate Limiting

• Implement exponential backoff for retries

• Cache responses when appropriate

• Monitor your usage to avoid limits

• Upgrade your plan if needed

Error Handling

try {
  const response = await fetch('https://api.solcognia.xyz/v1/models', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  const data = await response.json();
} catch (error) {
  console.error('API request failed:', error);
}

Permissions and Scopes

API Key Permissions

• models:read - Access AI model information

• models:use - Execute AI model requests

• workflows:read - View workflow information

• workflows:write - Create and modify workflows

• workflows:execute - Run workflow executions

• tokens:read - View token balance and history

• tokens:claim - Claim earned tokens

• user:read - Access user profile information

• user:write - Modify user profile

OAuth Scopes

• read_profile - Read user profile information

• manage_workflows - Create and manage workflows

• execute_workflows - Run workflow executions

• view_tokens - View token balance and transactions

• claim_tokens - Claim earned token rewards

Testing Authentication

Verify API Key

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.solcognia.xyz/v1/auth/verify

Response:

{
  "valid": true,
  "key_type": "production",
  "permissions": ["models:use", "workflows:execute"],
  "rate_limit": {
    "requests_per_hour": 1000,
    "remaining": 987
  }
}

Test OAuth Token

curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
     https://api.solcognia.xyz/v1/user/profile

Troubleshooting

Common Issues

401 Unauthorized

• Check that your API key is correct

• Ensure the key hasn't expired

• Verify you're using the correct authentication method

403 Forbidden

• Check that your API key has the required permissions

• Ensure you haven't exceeded rate limits

• Verify your account is in good standing

429 Too Many Requests

• Implement exponential backoff

• Check your rate limit status

• Consider upgrading your plan

Authentication features will be available with the Q4 2025 API launch.