Registering is straightforward. Visit our site, click the Signup button, and you’ll be redirected to the dashboard. From there, you can easily view and manage API keys, as well as handle user, wallet, and transaction management.
Two Ways to Authenticate
Oumla supports authentication through two methods:
- TypeScript SDK - Authentication is handled automatically when you initialize the client with your API key
- Direct REST API - Include your API key in the
x-api-key header for each request
Both methods use the same API key and provide identical functionality. Choose the method that best fits your project.
All requests to the Oumla API require the x-api-key header containing your API key.
curl -X GET "https://sandbox.oumla.com/api/v1/profiles" \
-H "x-api-key: your-api-key-here"
New to Oumla? Follow the Quick Start guide to create your account and get your first API key. API Key Authentication
Using the SDK
When using the TypeScript SDK, authentication is handled automatically:
import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';
const client = new OumlaSdkApiClient({
environment: OumlaSdkApiEnvironment.Sandbox,
apiKey: 'your-api-key-here' // Authentication handled automatically
});
// All SDK methods automatically include the API key
const profiles = await client.profiles.getProfiles();
Using Direct REST API Calls
When making direct HTTP requests, include your API key in the x-api-key header:
// Direct REST API call
const response = await fetch('https://sandbox.oumla.com/api/v1/profiles', {
headers: {
'x-api-key': 'your-api-key-here' // Required for all REST API calls
}
});
const data = await response.json();
API Key Management Best Practices
Never commit API keys to version control. Always use environment variables or secure secret management systems.
Environment Variables
Store your API key securely:
# .env file (never commit this!)
OUMLA_API_KEY=your-api-key-here
OUMLA_ENVIRONMENT=sandbox
// In your application
import { OumlaSdkApiClient, OumlaSdkApiEnvironment } from '@oumla/sdk';
const client = new OumlaSdkApiClient({
environment: process.env.OUMLA_ENVIRONMENT === 'production'
? OumlaSdkApiEnvironment.Production
: OumlaSdkApiEnvironment.Sandbox,
apiKey: process.env.OUMLA_API_KEY
});
Security Recommendations
- Use different API keys for different environments (sandbox vs production)
- Rotate API keys regularly for enhanced security
- Never share API keys in client-side code or public repositories
- Use environment-specific keys to prevent accidental production access
- Monitor API key usage in the dashboard for suspicious activity
Common Authentication Errors
Invalid API Key (401 - ERR_008)
{
"success": false,
"message": "You need to sign in to continue",
"code": "ERR_008",
"category": "UNKNOWN_ERROR",
"statusCode": 401,
"path": "/api/v1/profiles",
"timestamp": "2024-01-01T00:00:00.000Z",
"requestId": "req_123456789"
}
- API key is missing from request headers
- API key is incorrect or invalid
- API key has been revoked or expired
Solutions:
- Verify your API key in the dashboard
- Check that the
x-api-key header is included in your request
- Ensure there are no extra spaces or characters in the API key
- Generate a new API key if the current one is invalid
{
"success": false,
"message": "Invalid API key",
"code": "ERR_405",
"category": "UNKNOWN_ERROR",
"statusCode": 401
}
- API key format is incorrect
- API key is malformed
Solutions:
- Verify the API key format matches the expected pattern
- Regenerate the API key from the dashboard
- Check for copy-paste errors
Error Handling
Always handle authentication errors gracefully in your application:
import { OumlaSdkApiClient, OumlaSdkApiError } from '@oumla/sdk';
const client = new OumlaSdkApiClient({
environment: OumlaSdkApiEnvironment.Sandbox,
apiKey: process.env.OUMLA_API_KEY
});
try {
const profile = await client.profiles.createProfile({
reference: 'user-123',
type: 'User'
});
} catch (error) {
if (error instanceof OumlaSdkApiError) {
if (error.statusCode === 401) {
// Handle authentication error
console.error('Authentication failed:', error.message);
// Prompt user to check API key or re-authenticate
} else {
// Handle other errors
console.error('API error:', error.message);
}
} else {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
}
Rate Limiting
Rate limiting information will be provided here once available. Check the dashboard or contact support for current rate limits.
Mainnet Activation
Mainnet Activation RequiredTo activate mainnet access for Bitcoin (BTC) and Ethereum (ETH), you need to contact our support team and await approval. We will whitelist your account and require more information about your business.
Request Mainnet Activation
Click to send a pre-filled email to our support team
