Developers API

The Darukaa.Earth Developers API is designed for technical teams looking to deeply integrate Darukaa's capabilities into their own applications, automated workflows, or custom analytics pipelines.

While the standard API Overview covers the available endpoints, this guide focuses on the developer experience and integration patterns.

Getting Developer Access

Developers access Darukaa programmatically using the dedicated Dev user role.

1. Organization Context: There can be only one Dev user per organization (tied to the email domain).
2. Navigate to Users: An Admin must log into their Darukaa account and go to the Users management section in the Admin dashboard.
3. Open Developer Dialog: Click on the option to Create Developer.
4. Fill Details: Enter the required developer information:
5. First Name
6. Last Name
7. Organization Email
8. Secure Password
9. Create & Copy Key: Click Create. Upon successful creation, the platform will display the assigned API Key.
10. Key Storage: Click the Copy icon and store this key securely immediately. The full secret string will only be shown this one time.

(If a key is ever lost or compromised, an Admin can navigate to the API Keys management page to Regenerate or Revoke the key).

Authentication Format

API Keys follow the format drk_{env}_{random}. Include the API Key in the headers of all your requests:

X-API-Key: drk_prod_yourSecretKeyHere

Rate Limits and Usage Profiles

To ensure platform stability, Developer API access is governed by strict rate limits.

Dev User Limits

• 10 requests per second
• 500 requests per minute
• 10,000 requests per hour
• 100,000 requests per day

---

Create API Key

Creates a new API key for a specified user and environment.

POST https://api.darukaa.com/api/v1/api-keys/create

HTTP request

POST https://api.darukaa.com/api/v1/api-keys/create

Headers

Header	Value	Required
Authorization	Bearer	Yes

Query parameters

Field	Type	Required	Description
user_id	UUID	Yes	ID of the developer user
environment	string	Yes	Environment name (e.g., prod, staging)

Example request

cURLPythonJavaScript

curl -X POST "https://api.darukaa.com/api/v1/api-keys/create?user_id=123e4567-e89b-12d3-a456-426614174000&environment=prod" \
  -H "Authorization: Bearer <your_access_token>"

import requests

headers = {"Authorization": f"Bearer {access_token}"}
params = {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "environment": "prod"
}

response = requests.post(
    "https://api.darukaa.com/api/v1/api-keys/create",
    headers=headers,
    params=params
)

const response = await fetch('https://api.darukaa.com/api/v1/api-keys/create?user_id=123e4567-e89b-12d3-a456-426614174000&environment=prod', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const data = await response.json();

Status codes

Code	Description
201	Created - API key created successfully
400	Bad Request - User does not have Dev role
409	Conflict - API key already exists for this user
500	Internal Server Error

Response body

Success (201)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "api_key": "drk_prod_yourSecretKeyHere",
  "key_prefix": "drk_prod",
  "status": "active",
  "created_at": "2023-10-12T07:20:50.52Z",
  "message": "API key created successfully. Store this key securely."
}

Field	Type	Description
id	UUID string	Unique identifier for the API key
user_id	UUID string	ID of the developer user
api_key	string	Full API key (shown only once)
key_prefix	string	Prefix for identification
status	string	Status of the API key (e.g., active)
created_at	datetime	Timestamp when the key was created
message	string	System status message

---

Get API Key

Retrieves details of a specific API key.

GET https://api.darukaa.com/api/v1/api-keys/{api_key_id}

HTTP request

GET https://api.darukaa.com/api/v1/api-keys/{api_key_id}

Headers

Header	Value	Required
Authorization	Bearer	Yes

Path parameters

Field	Type	Required	Description
api_key_id	UUID	Yes	The ID of the API key to retrieve

Example request

cURL

curl -X GET https://api.darukaa.com/api/v1/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <your_access_token>"

Status codes

Code	Description
200	Success - API key retrieved
404	Not Found - API key not found

Response body

Success (200)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "key_prefix": "drk_prod",
  "status": "active",
  "created_at": "2023-10-12T07:20:50.52Z",
  "last_used_at": "2023-10-15T14:30:00.00Z",
  "expires_at": null,
  "user_name": "Jane Developer",
  "user_email": "jane@example.com"
}

Field	Type	Description
id	UUID string	Unique identifier for the API key
user_id	UUID string	ID of the developer user
key_prefix	string	Prefix for identification
status	string	Status of the API key (e.g., active, revoked)
created_at	datetime	Timestamp when the key was created
last_used_at	datetime/null	Timestamp when the key was last used
expires_at	datetime/null	Expiration timestamp
user_name	string/null	Name of the developer user
user_email	string/null	Email of the developer user

---

List API Keys

List all API keys with pagination and filtering.

GET https://api.darukaa.com/api/v1/api-keys

HTTP request

GET https://api.darukaa.com/api/v1/api-keys

Headers

Header	Value	Required
Authorization	Bearer	Yes

Query parameters

Field	Type	Required	Description
page	integer	No	Page number for pagination
per_page	integer	No	Number of items per page
status	string	No	Filter by status (active, revoked, expired)
user_id	UUID	No	Filter by specific user ID
sort_by	string	No	Field to sort by
sort_order	string	No	Sort order (asc or desc)

Example request

cURL

curl -X GET "https://api.darukaa.com/api/v1/api-keys?page=1&per_page=10&status=active" \
  -H "Authorization: Bearer <your_access_token>"

Status codes

Code	Description
200	Success - List of API keys retrieved
500	Internal Server Error

Response body

Success (200)

{
  "api_keys": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "key_prefix": "drk_prod",
      "status": "active",
      "created_at": "2023-10-12T07:20:50.52Z",
      "last_used_at": "2023-10-15T14:30:00.00Z",
      "expires_at": null,
      "user_name": "Jane Developer",
      "user_email": "jane@example.com"
    }
  ],
  "count": 1
}

Field	Type	Description
api_keys	array	List of API Key objects
count	integer	Total number of API keys matching the query

---

Revoke API Key

Revokes an active API key.

PUT https://api.darukaa.com/api/v1/api-keys/{api_key_id}/revoke

HTTP request

PUT https://api.darukaa.com/api/v1/api-keys/{api_key_id}/revoke

Headers

Header	Value	Required
Authorization	Bearer	Yes

Path parameters

Field	Type	Required	Description
api_key_id	UUID	Yes	The ID of the API key to revoke

Example request

cURL

curl -X PUT https://api.darukaa.com/api/v1/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6/revoke \
  -H "Authorization: Bearer <your_access_token>"

Status codes

Code	Description
200	Success - API key revoked successfully
404	Not Found - API key not found
500	Internal Server Error

---

Regenerate API Key

Regenerates a new API key for an existing one.

POST https://api.darukaa.com/api/v1/api-keys/{api_key_id}/regenerate

HTTP request

POST https://api.darukaa.com/api/v1/api-keys/{api_key_id}/regenerate

Headers

Header	Value	Required
Authorization	Bearer	Yes

Path parameters

Field	Type	Required	Description
api_key_id	UUID	Yes	The ID of the API key to regenerate

Example request

cURL

curl -X POST https://api.darukaa.com/api/v1/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6/regenerate \
  -H "Authorization: Bearer <your_access_token>"

Status codes

Code	Description
200	Success - API key regenerated successfully
404	Not Found - API key not found
500	Internal Server Error

Response body

Success (200)

{
  "api_key_id": "4gj85f64-5717-4562-b3fc-2c963f66afa7",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "api_key": "drk_prod_yourNewSecretKeyHere",
  "message": "API key regenerated successfully"
}

Field	Type	Description
api_key_id	UUID string	Unique identifier for the regenerated API key
user_id	UUID string	ID of the developer user
api_key	string	New full API key (shown only once)
message	string	System status message

---

Get API Key Usage

Retrieves usage details for a specific API key.

GET https://api.darukaa.com/api/v1/api-keys/{api_key_id}/usage

HTTP request

GET https://api.darukaa.com/api/v1/api-keys/{api_key_id}/usage

Headers

Header	Value	Required
Authorization	Bearer	Yes

Path parameters

Field	Type	Required	Description
api_key_id	UUID	Yes	The ID of the API key

Example request

cURL

curl -X GET https://api.darukaa.com/api/v1/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6/usage \
  -H "Authorization: Bearer <your_access_token>"

Status codes

Code	Description
200	Success - API key usage retrieved
404	Not Found - API key not found
500	Internal Server Error

---

Get API Key Permissions

Retrieves permissions for a specific API key.

GET https://api.darukaa.com/api/v1/api-keys/{api_key_id}/permissions

HTTP request

GET https://api.darukaa.com/api/v1/api-keys/{api_key_id}/permissions

Headers

Header	Value	Required
Authorization	Bearer	Yes

Path parameters

Field	Type	Required	Description
api_key_id	UUID	Yes	The ID of the API key

Example request

cURL

curl -X GET https://api.darukaa.com/api/v1/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6/permissions \
  -H "Authorization: Bearer <your_access_token>"

Status codes

Code	Description
200	Success - API key permissions retrieved
404	Not Found - API key not found
500	Internal Server Error

---

Developer Management API

The following endpoints allow administrators to manage Developer accounts programmatically.

---

Create Developer

Creates a new Developer account and returns a one-time API key. Only one Developer is allowed per organization.

POST https://api.darukaa.com/api/v1/developers

HTTP request

POST https://api.darukaa.com/api/v1/developers

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Request body

{
  "email": "dev@example.com",
  "first_name": "Jane",
  "last_name": "Developer",
  "password": "SecurePassword123!",
  "tnc_checked": true
}

Field	Type	Required	Description
email	string	Yes	Organization email address of the developer
first_name	string	Yes	First name of the developer
last_name	string	Yes	Last name of the developer
password	string	Yes	Secure password for the account
tnc_checked	boolean	Yes	Acceptance of Terms and Conditions

Status codes

Code	Description
201	Created - Developer account and API key created
409	Conflict - Developer already exists for this organization
500	Internal Server Error

Response body (201)

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "dev@example.com",
  "first_name": "Jane",
  "last_name": "Developer",
  "role": ["Dev"],
  "status": "active",
  "is_email_verified": true,
  "created_at": "2023-10-12T07:20:50.52Z",
  "updated_at": "2023-10-12T07:20:50.52Z",
  "api_key": "drk_prod_yourSecretKeyHere",
  "key_prefix": "drk_prod",
  "api_key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "api_key_expires_at": null,
  "message": "Developer account created successfully. API Key generated."
}

Field	Type	Description
user_id	UUID string	Unique identifier for the developer user
email	string	Organization email of the developer
first_name	string	First name
last_name	string	Last name
role	array	Assigned roles (e.g., ["Dev"])
status	string	Status of the user
is_email_verified	boolean	Email verification status
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
api_key	string/null	Full API key (shown only once)
key_prefix	string/null	Prefix of the generated API key
api_key_id	UUID string/null	ID of the generated API key
api_key_expires_at	datetime/null	Expiration timestamp of the generated key
message	string	System status message

---

Get Current Developer

Retrieves the profile of the currently authenticated developer.

GET https://api.darukaa.com/api/v1/developers/me

HTTP request

GET https://api.darukaa.com/api/v1/developers/me

Headers

Header	Value	Required
X-API-Key		Yes
Authorization	Bearer	Yes (Alternative)

Status codes

Code	Description
200	Success - Current developer profile retrieved

Response body (200)

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "dev@example.com",
  "first_name": "Jane",
  "last_name": "Developer",
  "role": ["Dev"],
  "status": "active",
  "is_email_verified": true,
  "created_at": "2023-10-12T07:20:50.52Z",
  "updated_at": "2023-10-12T07:20:50.52Z",
  "api_key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "api_key_expires_at": null
}

Field	Type	Description
user_id	UUID string	Unique identifier
email	string	Organization email
first_name	string	First name
last_name	string	Last name
role	array	Assigned roles
status	string	User status
is_email_verified	boolean	Email verification status
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
api_key_id	UUID string/null	API key ID currently in use
api_key_expires_at	datetime/null	Expiration timestamp of current key

---

Get Developer by ID

Retrieves a specific developer by their user ID.

GET https://api.darukaa.com/api/v1/developers/{user_id}

HTTP request

GET https://api.darukaa.com/api/v1/developers/{user_id}

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Path parameters

Field	Type	Required	Description
user_id	UUID	Yes	ID of the developer to retrieve

Status codes

Code	Description
200	Success - Developer retrieved
404	Not Found - Developer User not found

Response body

Matches the Get Current Developer response schema.

---

List Developers

Retrieves a paginated list of developer users.

GET https://api.darukaa.com/api/v1/developers

HTTP request

GET https://api.darukaa.com/api/v1/developers

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Query parameters

Field	Type	Required	Description
page	integer	No	Page number for pagination
per_page	integer	No	Number of items per page
status	string	No	Filter by user status
is_email_verified	boolean	No	Filter by verification status
query	string	No	Search by name or email
sort_by	string	No	Field to sort by
sort_order	string	No	Sort order (asc or desc)

Status codes

Code	Description
200	Success - List of developers retrieved

Response body (200)

{
  "users": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "dev@example.com",
      "first_name": "Jane",
      "last_name": "Developer",
      "role": ["Dev"],
      "status": "active",
      "is_email_verified": true,
      "created_at": "2023-10-12T07:20:50.52Z",
      "updated_at": "2023-10-12T07:20:50.52Z"
    }
  ],
  "count": 1
}

Field	Type	Description
users	array	List of developer user objects
count	integer	Total matched developers

---

Update Developer

Updates a developer's profile details.

PUT https://api.darukaa.com/api/v1/developers/{user_id}

HTTP request

PUT https://api.darukaa.com/api/v1/developers/{user_id}

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Request body

{
  "first_name": "Jane",
  "last_name": "Smith-Developer",
  "status": "active"
}

Field	Type	Required	Description
first_name	string	No	Updated first name
last_name	string	No	Updated last name
status	string	No	Updated status
is_email_verified	boolean	No	Updated email verification status

Status codes

Code	Description
200	Success - Developer updated
404	Not Found - Developer not found
409	Conflict - Developer with email already exists

Response body

Matches the user schema object returned in the List Developers endpoint.

---

Update Developer Status

Quickly updates just the developer's status.

PATCH https://api.darukaa.com/api/v1/developers/{user_id}/status

Request body

{
  "status": "inactive"
}

Status codes

Code	Description
200	Success - Developer status updated
404	Not Found - Developer not found

Response body

Matches the user schema object returned in the List Developers endpoint.

---

Delete Developer

Permanently removes a developer user.

DELETE https://api.darukaa.com/api/v1/developers/{user_id}

Status codes

Code	Description
200	Success - Developer deleted
404	Not Found - Developer not found

Response body

Matches the user schema object returned in the List Developers endpoint.

---

For complete endpoint documentation, refer to the Main API Reference.

---

Assign Endpoint To Developer

Assign an API endpoint to a developer (admin only).

POST https://api.darukaa.com/api/v1/developers/{developer_id}/permissions

HTTP request

POST https://api.darukaa.com/api/v1/developers/{developer_id}/permissions

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Path parameters

Field	Type	Required	Description
developer_id	UUID string	Yes	ID of the developer to assign endpoint

Request body

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "endpoint_id": "456e7890-e89b-12d3-a456-426614174000",
  "status": "active"
}

Field	Type	Required	Description
user_id	UUID string	Yes	User ID of the developer
endpoint_id	UUID string	Yes	API Endpoint ID to assign
status	string	No	Permission status: 'active' or 'inactive' (default: active)

Status codes

Code	Description
201	Created - Endpoint assigned successfully

Response body (201)

{
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "endpoint_id": "456e7890-e89b-12d3-a456-426614174000",
  "status": "active",
  "granted_at": "2023-10-12T07:20:50.52Z",
  "endpoint": null
}

---

List Developer Permissions

List all permissions (assigned endpoints) for a developer (admin only).

GET https://api.darukaa.com/api/v1/developers/{developer_id}/permissions

HTTP request

GET https://api.darukaa.com/api/v1/developers/{developer_id}/permissions

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Path parameters

Field	Type	Required	Description
developer_id	UUID string	Yes	ID of the developer

Query parameters

Field	Type	Required	Description
status_filter	string	No	Filter by status: 'active' or 'inactive'

Status codes

Code	Description
200	Success - List of permissions retrieved

Response body (200)

{
  "permissions": [
    {
      "id": "789e0123-e89b-12d3-a456-426614174000",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "endpoint_id": "456e7890-e89b-12d3-a456-426614174000",
      "status": "active",
      "granted_at": "2023-10-12T07:20:50.52Z",
      "endpoint": null
    }
  ],
  "count": 1
}

---

Bulk Assign Endpoints To Developer

Bulk assign multiple endpoints to a developer (admin only).

POST https://api.darukaa.com/api/v1/developers/{developer_id}/permissions/bulk

HTTP request

POST https://api.darukaa.com/api/v1/developers/{developer_id}/permissions/bulk

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Path parameters

Field	Type	Required	Description
developer_id	UUID string	Yes	ID of the developer

Request body

{
  "endpoint_ids": [
    "456e7890-e89b-12d3-a456-426614174000",
    "567e8901-e89b-12d3-a456-426614174000"
  ],
  "status": "active"
}

Status codes

Code	Description
201	Created - Endpoints assigned successfully

Response body (201)

Returns an array of created permissions.

[
  {
    "id": "789e0123-e89b-12d3-a456-426614174000",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "endpoint_id": "456e7890-e89b-12d3-a456-426614174000",
    "status": "active",
    "granted_at": "2023-10-12T07:20:50.52Z",
    "endpoint": null
  }
]

---

Revoke Endpoint From Developer

Revoke specific endpoint access from a developer (admin only).

DELETE https://api.darukaa.com/api/v1/developers/{developer_id}/permissions/{endpoint_id}

HTTP request

DELETE https://api.darukaa.com/api/v1/developers/{developer_id}/permissions/{endpoint_id}

Headers

Header	Value	Required
Authorization	Bearer	Yes (Admin)

Path parameters

Field	Type	Required	Description
developer_id	UUID string	Yes	ID of the developer
endpoint_id	UUID string	Yes	ID of the endpoint to revoke

Status codes

Code	Description
200	Success - Permission revoked successfully

Response body (200)

Returns the revoked permission object.

{
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "endpoint_id": "456e7890-e89b-12d3-a456-426614174000",
  "status": "inactive",
  "granted_at": "2023-10-12T07:20:50.52Z",
  "endpoint": null
}