Authentication

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.

Request Headers

All requests to the Oumla API require the x-api-key header containing your API key.

Here’s how to include your API key in requests:

curl -X GET "https://sandbox.oumla.com/api/v1/profiles" \
  -H "x-api-key: your-api-key-here"

const response = await fetch('https://sandbox.oumla.com/api/v1/profiles', {
  headers: {
    'x-api-key': 'your-api-key-here'
  }
});

const data = await response.json();
console.log(data);

import requests

headers = {
    'x-api-key': 'your-api-key-here'
}

response = requests.get('https://sandbox.oumla.com/api/v1/profiles', headers=headers)
print(response.json())

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://sandbox.oumla.com/api/v1/profiles"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("x-api-key", "your-api-key-here")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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"
}

Causes:

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

Invalid API Key Format (401 - ERR_405)

{
  "success": false,
  "message": "Invalid API key",
  "code": "ERR_405",
  "category": "UNKNOWN_ERROR",
  "statusCode": 401
}

Causes:

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

Getting Started

Core Concepts

Workflows

Resources

Two Ways to Authenticate

Request Headers

API Key Authentication

Using the SDK

Using Direct REST API Calls

API Key Management Best Practices

Environment Variables

Security Recommendations

Common Authentication Errors

Invalid API Key (401 - ERR_008)

Invalid API Key Format (401 - ERR_405)

Error Handling

Rate Limiting

Mainnet Activation

Request Mainnet Activation

​Two Ways to Authenticate

​Request Headers

​API Key Authentication

​Using the SDK

​Using Direct REST API Calls

​API Key Management Best Practices

​Environment Variables

​Security Recommendations

​Common Authentication Errors

​Invalid API Key (401 - ERR_008)

​Invalid API Key Format (401 - ERR_405)

​Error Handling

​Rate Limiting

​Mainnet Activation

Request Mainnet Activation

Two Ways to Authenticate

Request Headers

API Key Authentication

Using the SDK

Using Direct REST API Calls

API Key Management Best Practices

Environment Variables

Security Recommendations

Common Authentication Errors

Invalid API Key (401 - ERR_008)

Invalid API Key Format (401 - ERR_405)

Error Handling

Rate Limiting

Mainnet Activation