API Reference
Organizations

Organization Endpoints

Overview

This document provides details on the Organization Management endpoints, their functionality, expected use cases, and examples for integration with tools like cURL.

1. Get Organization Information

Description

This endpoint retrieves all organizations associated with the authenticated user.
It validates the user's token and fetches the organizations from the database.

When to Use

  • To list the organizations that a user is associated with.
  • To display an overview of the user's organizations in a dashboard.

Endpoint Details

  • Method: GET
  • Path: /organizations
  • Headers:
    • Authorization: Bearer <token> (Required)

Response

  • Success (200 OK):
[
  {
    "id": "org123",
    "name": "Organization One",
    "description": "Description of Organization One",
    "created_by": "user123",
    "created_at": "2024-12-01T10:00:00Z"
  },
  {
    "id": "org456",
    "name": "Organization Two",
    "description": "Description of Organization Two",
    "created_by": "user123",
    "created_at": "2024-12-02T14:00:00Z"
  }
]
  • Error Responses:
    • 401 Unauthorized: Token claims missing or invalid.
    • 400 Bad Request: Invalid user ID.
    • 500 Internal Server Error: Failed to retrieve organizations.

cURL Example

curl -X GET http://localhost:3010/api/organizations \
-H "Authorization: Bearer <token>"

2. Create New Organization

Description

This endpoint creates a new organization.
It validates the user's token, processes the request payload, and saves the organization to the database. It also assigns the authenticated user as the owner of the organization.

When to Use

  • When a new organization needs to be created.
  • When a user wants to establish a group or workspace.

Note: This endpoint is restricted to users with the owner or admin roles, as determined by the JWT token validation.

Endpoint Details

  • Method: POST
  • Path: /organizations
  • Headers:
    • Authorization: Bearer <token> (Required)

Request Payload

{
  "organization_name": "New Organization",
  "organization_description": "This is a description of the new organization."
}

Response

  • Success (201 Created):
{
  "organization_id": "org789",
  "user_id": "user123",
  "role": "owner"
}
  • Error Responses:
    • 401 Unauthorized: Token claims missing or invalid.
    • 400 Bad Request: Invalid request body or user ID.
    • 500 Internal Server Error: Failed to create organization.

cURL Example

curl -X POST http://localhost:3010/api/organizations \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "organization_name": "New Organization",
  "organization_description": "This is a description of the new organization."
}'
UserOrganization User