Accounts

Audience: Developers

Accounts API Contract

Overview

The Accounts API provides endpoints for managing API accounts and authentication keys. All account management endpoints require the master API key.

Authentication: All endpoints require the X-API-Key header with the master API key (from GL_DEEP_RESEARCH_MASTER_API_KEY environment variable).

---

Create Account (POST /v1/accounts/)

Create a new account and receive an API key. The API key is only returned once during creation - store it securely!

Authentication: Master API key required

Request:

curl -X POST https://stag-gl-deep-research.obrol.id/v1/accounts/ \
  -H "X-API-Key: your-master-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-account"
  }'

Request Body:

Field	Type	Required	Description
name	string	Yes	Account name (must be unique)

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "api_key": "aB3dEf9gHiJkLmNoPqRsTuVwXyZ123456"
  },
  "message": "Account created successfully"
}

Response Fields:

Field	Type	Description
success	boolean	Indicates if the request was successful
data.id	string	Account UUID
data.api_key	string	API key for this account (only returned once)
message	string	Success message

Error Responses:

• 409 Conflict: Account already exists

  {
    "detail": "Account 'my-account' already exists"
  }

• 400 Bad Request: Invalid request data

  {
    "detail": "Account name (must be unique)"
  }

• 401 Unauthorized: Invalid or missing API key

  {
    "detail": "Invalid API key"
  }

⚠️ Important: The API key is only returned once during account creation. Store it securely!

---

List Accounts (GET /v1/accounts/)

List all accounts in the system.

Authentication: Master API key required

Request:

curl https://stag-gl-deep-research.obrol.id/v1/accounts/ \
  -H "X-API-Key: your-master-api-key"

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "my-account",
      "key_preview": "aB3...456",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "message": "Accounts retrieved successfully"
}

Response Fields:

Field	Type	Description
success	boolean	Indicates if the request was successful
data	array	List of account objects
data[].id	string	Account UUID
data[].name	string	Account name
data[].key_preview	string	Preview of the API key (first 3 + last 3 chars)
data[].created_at	string	Account creation timestamp (ISO 8601)
message	string	Success message

Error Responses:

• 401 Unauthorized: Invalid or missing API key

  {
    "detail": "Invalid API key"
  }

• 500 Internal Server Error: Master API key not configured

  {
    "detail": "Master API key not configured"
  }

---

Get Account (GET /v1/accounts/{account_id})

Get account information by ID.

Authentication: Master API key required

Request:

curl https://stag-gl-deep-research.obrol.id/v1/accounts/your-account-id-here \
  -H "X-API-Key: your-master-api-key"

Path Parameters:

Parameter	Type	Required	Description
account_id	string	Yes	Account UUID

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "my-account",
    "key_preview": "aB3...456",
    "created_at": "2025-01-15T10:00:00Z"
  },
  "message": "Account retrieved successfully"
}

Response Fields:

Field	Type	Description
success	boolean	Indicates if the request was successful
data.id	string	Account UUID
data.name	string	Account name
data.key_preview	string	Preview of the API key (first 3 + last 3 chars)
data.created_at	string	Account creation timestamp (ISO 8601)
message	string	Success message

Error Responses:

• 404 Not Found: Account not found

  {
    "detail": "Account '123e4567-e89b-12d3-a456-426614174000' not found"
  }

• 401 Unauthorized: Invalid or missing API key

  {
    "detail": "Invalid API key"
  }

---

Delete Account (DELETE /v1/accounts/{account_id})

Soft delete an account by ID. The account is marked as deleted but data is retained for audit purposes.

Authentication: Master API key required

Request:

curl -X DELETE https://stag-gl-deep-research.obrol.id/v1/accounts/to-be-deleted-account-id-here \
  -H "X-API-Key: your-master-api-key"

Path Parameters:

Parameter	Type	Required	Description
account_id	string	Yes	Account UUID

Response (200 OK):

{
  "success": true,
  "message": "Account '123e4567-e89b-12d3-a456-426614174000' deleted successfully"
}

Response Fields:

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	Success message

Error Responses:

• 404 Not Found: Account not found

  {
    "detail": "Account '123e4567-e89b-12d3-a456-426614174000' not found"
  }

• 401 Unauthorized: Invalid or missing API key

  {
    "detail": "Invalid API key"
  }

Note: This performs a soft delete - the account is marked as deleted but data is retained for audit purposes.

---

Authentication

API Key Types

The system supports two types of API keys:

1. Master API Key: System-wide administrative key

   • Set via GL_DEEP_RESEARCH_MASTER_API_KEY environment variable

   • Required for: Account management, Profile management

   • Provides full system access

2. Account API Key: Per-account keys

   • Generated when creating accounts via POST /v1/accounts/

   • Required for: Research endpoints, Task endpoints

   • Scoped to the specific account

Using API Keys

Include the API key in the X-API-Key header for all authenticated requests:

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/taskgroup' \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'query=What is AI?' \
  --data-urlencode 'profile=ESSENTIAL'

Security Features

• ✅ Bcrypt hashing: API keys are hashed using bcrypt before storage

• ✅ Salt per key: Each key gets a unique salt automatically

• ✅ Preview optimization: Reduces bcrypt operations by filtering candidates

• ✅ Constant-time comparison: Bcrypt prevents timing attacks

• ✅ No plaintext storage: Keys are hashed immediately after generation

• ✅ Key preview: Only first 3 and last 3 characters are shown in responses

---

Usage Flow

1. Set master API key in environment variable (GL_DEEP_RESEARCH_MASTER_API_KEY)

2. Create an account using POST /v1/accounts/ with master key

3. Save the API key returned in the response (only returned once!)

4. Use the account API key in X-API-Key header for research and task endpoints

5. Use the master API key for administrative operations (accounts, profiles)