Authentication

Developer

Tip

API token authentication is the recommended method for external integrations. Tokens are linked to a specific product and offer granular access control.

Authentication Methods

Prodgy supports two authentication methods for API access:

Method	Recommended use	Header
API Token	External integrations and automations	X-API-Token: prodgy_...
JWT	Authenticated user sessions	Authorization: Bearer <jwt>

For external integrations, always use API tokens.

---

Organization Context Header (Super Admin)

Super Admin users can override their organization context by sending the X-Organization-Id header with any request. This allows them to operate in the context of a different organization than their profile’s default.

X-Organization-Id: 6480d1ad-5535-40e1-95b0-05774d3dc4b0

Note

This header is only honored for Super Admin users. For regular Admin and User roles, it is ignored — the organization is always determined by the JWT token.

The header must contain a valid UUID. It is automatically injected by the Prodgy frontend when a Super Admin selects an organization in the sidebar dropdown.

---

API Token

Format

Tokens follow the format:

prodgy_<random_characters>

Example: prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c

How to Send the Token

Include the token in one of the following header formats:

X-API-Token: prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c

or

Authorization: Bearer prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c

cURL Example

curl -X GET https://<instance>/api/agent-base/product/<product_id> \
  -H "X-API-Token: prodgy_k8d9Jf2kL9mP3qR4sT5uV6wX7yZ8aB9c"

---

Available Endpoints

The following endpoints are accessible via API Token, grouped by category:

Agent Base

Endpoint	Methods	Description
/api/agent-base	GET, POST, DELETE	List, install and uninstall agents for a workspace
/api/agent-base/{id}/executions	GET	List executions for a specific agent
/api/agent-base/triggers	GET, POST	List and execute manual triggers

Workflow Executor

Endpoint	Methods	Description
/api/workflow/execute	POST	Execute a workflow test
/api/workflow/{executionId}/status	GET	Get execution status
/api/workflow/{executionId}/events	GET	Stream execution events (SSE)
/api/workflow/{executionId}/stop	POST	Stop a running execution
/api/workflow/{executionId}/pause	POST	Pause a running execution
/api/workflow/{executionId}/continue	POST	Resume a paused execution

Workflow Base

Endpoint	Methods	Description
/api/workflow-base	GET, POST, PUT, DELETE	Manage workflow base definitions

Nodes Executor

Endpoint	Methods	Description
/api/nodes/execute	POST	Execute a single node
/api/nodes/status/{nodeId}	GET	Get node execution status

Integrations Base

Endpoint	Methods	Description
/api/integrations-base	GET, POST, PUT, DELETE	Manage integration configurations
/api/external/integrations	GET	List active integrations for the organization

Knowledge Base

Endpoint	Methods	Description
/api/knowledge-base/{productId}	GET	List knowledge bases for a workspace
/api/knowledge-base/embeddings	GET, POST, PUT, DELETE	Manage embeddings and semantic search
/api/knowledge-base/storage	GET, POST, PUT, DELETE	Upload, download and manage files

Assistant

Endpoint	Methods	Description
/api/assistant/chat	POST	Send a message and receive AI response (streaming)
/api/assistant/chat/history	GET	Retrieve chat session history

API Tokens

Endpoint	Methods	Description
/api/api-token/auth/validate	GET	Validate the current API token

Note

Endpoints for managing agents (CRUD) and workflows (CRUD) are not accessible via API Token. They require internal authentication (JWT or backend service token).

Tip

For full endpoint details, request/response schemas and live testing, visit the interactive Swagger documentation at https://<your-api-host>/swagger.

---

Creating a Token

Tokens are created through the Prodgy interface or via API (with JWT authentication).

Via Interface

1. Go to workspace settings (gear button in the navbar)
2. Click the API Tokens tab
3. Click Create Token
4. Enter the name and, optionally, an expiration date
5. Copy the generated token — it is displayed only once

Via API

POST /api/api-tokens
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "product_id": "644c3604-4fd3-4681-846b-8ae14f18f00d",
  "token_name": "My Integration",
  "expires_at": "2026-12-31T23:59:59Z"
}

Response (201):

{
  "success": true,
  "message": "API token created successfully",
  "data": {
    "id": "uuid",
    "token": "prodgy_...",
    "token_name": "My Integration",
    "token_prefix": "prodgy_k8...",
    "product_id": "644c3604-...",
    "expires_at": "2026-12-31T23:59:59Z",
    "created_at": "2026-03-05T10:00:00Z"
  }
}

Caution

The full token is displayed only once at creation. After closing the dialog or the API response, only the prefix will be available. Store the token in a safe place.

---

Validating a Token

To check if a token is valid:

GET /api/api-token/auth/validate
X-API-Token: prodgy_<token>

Response (200) — Valid token:

{
  "success": true,
  "authType": "api_token",
  "userId": "uuid",
  "productId": "uuid",
  "organizationId": "uuid",
  "apiTokenId": "uuid"
}

Response (401) — Invalid token:

{
  "error": "Unauthorized",
  "message": "Invalid API token"
}

---

Managing Tokens via API

List Product Tokens

GET /api/api-tokens/product/{productId}
Authorization: Bearer <jwt_token>

Update Token

PUT /api/api-tokens/{id}
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "token_name": "New Name",
  "is_active": true,
  "expires_at": "2027-06-30T23:59:59Z"
}

Revoke Token

POST /api/api-tokens/{id}/revoke
Authorization: Bearer <jwt_token>

Renew Expiration

POST /api/api-tokens/{id}/renew
Content-Type: application/json
Authorization: Bearer <jwt_token>

{
  "expires_at": "2027-12-31T23:59:59Z"
}

Regenerate Token

POST /api/api-tokens/{id}/regenerate
Authorization: Bearer <jwt_token>

Note

When regenerating, a new token is created and the previous one is archived. The new token is displayed only once in the response.

Delete Token

DELETE /api/api-tokens/{id}
Authorization: Bearer <jwt_token>

---

Audit Logs

Each token usage is automatically logged. To query the logs:

GET /api/api-tokens/{id}/audit-logs?limit=100
Authorization: Bearer <jwt_token>

Response:

{
  "success": true,
  "data": [
    {
      "action": "used",
      "ip_address": "192.168.1.100",
      "user_agent": "curl/7.88.0",
      "endpoint": "/api/agent-base/product/...",
      "status_code": 200,
      "created_at": "2026-03-05T14:30:00Z"
    }
  ]
}

Registered Action Types

Action	Description
created	Token was created
used	Token was used in a request
revoked	Token was revoked
expired	Token expired
renewed	Token expiration was extended
regenerated	New token was generated from the previous one

---

Best Practices

• Use HTTPS for all requests in production
• Never expose tokens in code repositories or public logs
• Configure expiration dates for temporary tokens
• Rotate tokens periodically using the regenerate function
• Monitor audit logs to detect suspicious access
• Use one token per integration for easier tracking