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

# Developer Apps

> Create and manage developer applications for accessing OTP services and advanced integrations with Briq's SMS platform.

# Developer Apps

Developer Apps provide access to advanced Briq features, particularly OTP services. They act as secure integrations scoped to workspaces with developer access enabled. Each app represents a distinct client integration — your mobile app, web service, or backend.

## What are Developer Apps?

Developer Apps are client applications that enable access to OTP services and other developer-restricted features in the Briq platform. You bind an **API Key** to a Developer App so Karibu resolves the app from `X-API-Key` on every request. You do **not** send `app_key` in request bodies once the key is bound.

### Key Characteristics

* **OTP Access**: Required context for all OTP request and verification operations
* **API Key Binding**: Bind one API key per app per environment; Karibu resolves the app from `X-API-Key`
* **Workspace Linking**: Must be linked to workspaces with developer access enabled
* **Secure Integration**: Provide controlled, auditable access to advanced features

## Requirements for Developer Apps

### Workspace Access

* Developer apps can only work with workspaces that have `developer_access = true`
* You must enable developer access on your workspace before creating apps

### API Key Binding

* OTP and other developer-restricted APIs require an API key bound to a Developer App
* Bind at key creation (`POST /api-keys/?developer_app_id={app_id}`) or attach an existing key (`POST /developer-apps/{app_id}/api-keys/{api_key_id}/attach`)
* Once bound, only `X-API-Key` is required in request headers — do not send `app_key` in the body

### `app_key` on the Developer App record

* Each Developer App has an `app_key` returned in API responses (for dashboard and admin use)
* `app_key` is **not** a request credential when your API key is bound to the app

## Managing Developer Apps

### Creating a Developer App

```bash theme={null}
curl -X POST https://karibu.briq.tz/v1/developer_apps/ \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
  "app_name": "My Authentication App",
  "app_description": "Developer app for OTP authentication services",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}'
```

**Response:**

```json theme={null}
{
  "app_id": "dapp_123456789",
  "app_key": "devapp_abcdef123456",
  "app_name": "My Authentication App",
  "app_description": "Developer app for OTP authentication services",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "created_at": "2024-08-10T10:30:00Z",
  "is_active": true
}
```

### Binding an API Key to a Developer App

Bind at creation time:

```bash theme={null}
curl -X POST "https://karibu.briq.tz/api-keys/?developer_app_id=dapp_123456789" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
  "name": "Production OTP Key"
}'
```

Or attach an existing API key:

```bash theme={null}
curl -X POST https://karibu.briq.tz/developer-apps/dapp_123456789/api-keys/key_abc123/attach \
-H "X-API-Key: your_api_key_here"
```

**Response:**

```json theme={null}
{
  "message": "API key successfully attached to developer app."
}
```

### Listing Developer Apps

```bash theme={null}
curl -X GET "https://karibu.briq.tz/v1/developer_apps/?workspace_id=0967198e-ec7b-4c6b-b4d3-f71244cadbe9" \
-H "X-API-Key: your_api_key_here"
```

**Response:**

```json theme={null}
[
  {
    "app_id": "dapp_123456789",
    "app_key": "devapp_abcdef123456",
    "app_name": "My Authentication App",
    "app_description": "Developer app for OTP authentication services",
    "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
    "created_at": "2024-08-10T10:30:00Z",
    "is_active": true
  }
]
```

### Getting Developer App Details

```bash theme={null}
curl -X GET https://karibu.briq.tz/v1/developer_apps/dapp_123456789 \
-H "X-API-Key: your_api_key_here"
```

### Updating a Developer App

```bash theme={null}
curl -X PUT https://karibu.briq.tz/v1/developer_apps/dapp_123456789 \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
  "app_name": "Updated Authentication App",
  "app_description": "Updated developer app for enhanced OTP services",
  "is_active": true
}'
```

### Listing API Keys for a Developer App

```bash theme={null}
curl -X GET https://karibu.briq.tz/developer-apps/dapp_123456789/api-keys \
-H "X-API-Key: your_api_key_here"
```

## Using Developer Apps with OTP

Once your API key is bound to a Developer App, OTP requests require only the `X-API-Key` header. Do not include `app_key` in the request body.

```bash theme={null}
curl -X POST https://karibu.briq.tz/v1/otp/request \
-H "Content-Type: application/json" \
-H "X-API-Key: your_bound_api_key_here" \
-d '{
  "phone_number": "255712345678",
  "sender_id": "BRIQ OTP",
  "otp_length": 6,
  "minutes_to_expire": 10,
  "delivery_method": "sms",
  "message_template": "Your OTP is {code}"
}'
```

## Best Practices

### Developer App Management

1. **Descriptive Names**: Use clear `app_name` values that indicate the app's purpose
2. **Workspace Linking**: Ensure apps are linked to workspaces with developer access
3. **One Key Per App Per Environment**: Bind a dedicated API key to each Developer App in each environment (development, staging, production)
4. **Regular Review**: Periodically review and clean up unused apps

### Security Considerations

1. **API Key Rotation**: Rotate API keys (not `app_key`) when credentials are compromised or on a schedule — create a new key, attach it, migrate traffic, then revoke the old key
2. **Key Confidentiality**: Treat bound API keys as secrets; never expose them in client-side code
3. **Monitoring**: Track API key usage and access patterns per Developer App
4. **Environment Separation**: Use separate Developer Apps and bound API keys for development and production

### Integration Tips

1. **Error Handling**: Implement robust error handling for app creation, key binding, and OTP calls
2. **Testing**: Test the full flow (create app → bind key → call OTP) in a development environment before production
3. **Logging**: Log OTP and API activity server-side for debugging and monitoring
4. **Deactivation**: Set `is_active = false` on unused apps instead of deleting them