Skip to main content

​
Overview

Clients represent the organizations or individuals who receive licenses for your projects. Each client can have multiple projects and licenses associated with them.

​
Create Client

Create a new client record.

​
Endpoint

POST /clients
This endpoint requires authentication. Include a valid JWT token in the Authorization header.

​
Authentication

Include the JWT token in the Authorization header: 
Authorization: Bearer <your-jwt-token>

​
Request Body

​
name
string
required
Client’s name or company name
​
email
string
required
Client’s email address (must be unique)

​
Example Request

curl -X POST https://your-keybox-server.com/clients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "name": "Acme Corporation",
    "email": "[email protected]"
  }'

​
Response

​
message
string
Success message
​
client
object
The created client object

​
Example Response

{
  "message": "Client created successfully",
  "client": {
    "_id": "60f7b3b3e6b3a72e8c8e4a1a",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "owner": "60f7b3b3e6b3a72e8c8e4a19",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

​
Error Responses

​
Missing Name

Status Code: 400 
{
  "message": "Client name required"
}

​
Missing Email

Status Code: 400 
{
  "message": "Client email required"
}

​
Duplicate Email

Status Code: 409 
{
  "message": "Client with this email already exists",
  "field": "email"
}

​
Validation Error

Status Code: 400 
{
  "message": "Validation error",
  "errors": { ... },
  "details": "Detailed validation error message"
}

​
Unauthorized

Status Code: 401 
{
  "message": "Unauthorized"
}

​
Server Error

Status Code: 500 
{
  "message": "Internal server error",
  "error": "Detailed error message"
}

​
Client Ownership

Clients are owned by the authenticated user who creates them:
  • The owner field is automatically set to the authenticated user’s ID
  • Only clients owned by the authenticated user are visible in dashboard queries
  • This ensures data isolation between different users/developers

​
Client Relationships

Clients are at the top of the KeyBox data hierarchy: 
Client
  └─ Projects
       └─ Licenses
  • A client can have multiple projects
  • Each project can have multiple licenses
  • When you fetch dashboard data, clients are returned with their nested projects and licenses

​
Complete Example

class ClientManager {
  constructor(serverUrl, authToken) {
    this.serverUrl = serverUrl;
    this.authToken = authToken;
  }

  async createClient(name, email) {
    try {
      const response = await fetch(`${this.serverUrl}/clients`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.authToken}`
        },
        body: JSON.stringify({ name, email })
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || `HTTP ${response.status}`);
      }

      const data = await response.json();
      console.log('Client created:', data.client.name);
      console.log('Client ID:', data.client._id);
      
      return data.client;
    } catch (error) {
      console.error('Failed to create client:', error.message);
      throw error;
    }
  }
}

// Usage
const manager = new ClientManager(
  'https://your-keybox-server.com',
  'your-jwt-token'
);

try {
  const client = await manager.createClient(
    'Acme Corporation',
    '[email protected]'
  );
  
  // Use the client ID for creating projects
  console.log('Use this ID to create projects:', client._id);
} catch (error) {
  if (error.message.includes('already exists')) {
    console.log('Client already registered');
  }
}

​
Workflow Example

Typical workflow for onboarding a new client:
1

Create Client

Create a client record with their name and email
2

Create Project

Create a project for the client using the client ID
3

Generate License

Create a license for the project
4

Deliver License

Send the license key to the client
5

Client Activation

Client activates the license in their application

​
Best Practices

Unique Emails

Use unique email addresses for each client to prevent conflicts

Descriptive Names

Use clear, descriptive names (company names or full names)

Validation

Validate email format before submitting

Error Handling

Handle duplicate email errors gracefully

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us