> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oumla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Oumla API

export const apiKeysUrl = 'https://dashboard.oumla.com/dashboard/apikeys';

export const dashboardUrl = 'https://dashboard.oumla.com';

export const supportEmail = 'support@oumla.com';

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**:

1. **TypeScript SDK** - Authentication is handled automatically when you initialize the client with your API key
2. **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

<Info>
  All requests to the Oumla API require the `x-api-key` header containing your API key.
</Info>

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://sandbox.oumla.com/api/v1/profiles" \
    -H "x-api-key: your-api-key-here"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

<Note>
  **New to Oumla?** Follow the [Quick Start](/guides/quickstart) guide to create your account and get your first API key.
</Note>

## API Key Authentication

### Using the SDK

When using the TypeScript SDK, authentication is handled automatically:

```javascript theme={null}
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:

```javascript theme={null}
// 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

<Warning>
  **Never commit API keys to version control.** Always use environment variables or secure secret management systems.
</Warning>

### Environment Variables

Store your API key securely:

```bash theme={null}
# .env file (never commit this!)
OUMLA_API_KEY=your-api-key-here
OUMLA_ENVIRONMENT=sandbox
```

```javascript theme={null}
// 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

1. **Use different API keys for different environments** (sandbox vs production)
2. **Rotate API keys regularly** for enhanced security
3. **Never share API keys** in client-side code or public repositories
4. **Use environment-specific keys** to prevent accidental production access
5. **Monitor API key usage** in the dashboard for suspicious activity

## Common Authentication Errors

### Invalid API Key (401 - ERR\_008)

```json theme={null}
{
  "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:**

1. Verify your API key in the <a href={apiKeysUrl} target="_blank" rel="noopener noreferrer">dashboard</a>
2. Check that the `x-api-key` header is included in your request
3. Ensure there are no extra spaces or characters in the API key
4. Generate a new API key if the current one is invalid

### Invalid API Key Format (401 - ERR\_405)

```json theme={null}
{
  "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:**

1. Verify the API key format matches the expected pattern
2. Regenerate the API key from the dashboard
3. Check for copy-paste errors

## Error Handling

Always handle authentication errors gracefully in your application:

```javascript theme={null}
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

<Info>
  Rate limiting information will be provided here once available. Check the dashboard or contact support for current rate limits.
</Info>

## Mainnet Activation

<Warning>
  **Mainnet Activation Required**

  To 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.
</Warning>

<Card title="Request Mainnet Activation" href={`mailto:${supportEmail}?subject=Mainnet%20Activation%20Request&body=Hello%20Oumla%20Team,%0A%0AI%20would%20like%20to%20request%20mainnet%20activation%20for%20my%20account.%0A%0ACompany%20Details:%0A-%20Company%20Name:%20%0A-%20Website:%20%0A%0AMainnet%20Requirements:%0A-%20Networks%20Needed:%20(BTC%20/%20ETH%20/%20Both)%0A-%20Use%20Case:%20%0A-%20Expected%20Volume:%20%0A-%20Timeline:%20%0A%0APlease%20let%20me%20know%20what%20additional%20information%20you%20need.%0A%0AThank%20you!`}>
  Click to send a pre-filled email to our support team
</Card>