​

Developer Apps

​

What are Developer Apps?

​

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

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

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

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

curl -X POST https://karibu.briq.tz/developer-apps/dapp_123456789/api-keys/key_abc123/attach \
-H "X-API-Key: your_api_key_here"

{
  "message": "API key successfully attached to developer app."
}

​

Listing Developer Apps

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"

[
  {
    "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

curl -X GET https://karibu.briq.tz/v1/developer_apps/dapp_123456789 \
-H "X-API-Key: your_api_key_here"

​

Updating a Developer App

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

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

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