Authentication

Dcycle supports multiple authentication methods depending on how you’re integrating:

API Keys

For REST API and programmatic integrations

CLI Login

For command-line tool access

MCP Setup

For AI assistant integrations

API Key Authentication

API Keys are the primary method for authenticating with the Dcycle REST API.

When to Use API Keys

Server-to-server integrations
Automated scripts and CI/CD pipelines
Backend applications
Any programmatic access

Get an API Key

Go to app.dcycle.io

Navigate to API Keys

Organization Settings → API Keys

Generate a new key

Click “Generate API Key”

The API Key is only shown once. Save it immediately.

User Attribution & Accountability

Important: When you create an API key, you are authorizing it to perform actions on your behalf. All data uploaded using that key will be attributed to you (the API key creator) for audit and compliance purposes.

This means:

✅ All records created via your API key are linked to your user account
✅ Audit logs will show you as the creator of the data
✅ This ensures proper data governance and traceability
✅ You are responsible for the data uploaded using your API keys

Best Practice: Create separate API keys for different environments (dev, staging, prod) and name them descriptively (e.g., “Production ETL Pipeline”, “Testing Environment”) to easily track their usage.

Using your API Key

Include your API Key in requests using the appropriate format for your API version:

New API (Recommended)
Legacy API

# New API endpoints (e.g., /api/v1/logistics/requests)
curl -X POST "https://api.dcycle.io/api/v1/logistics/requests" \
  -H "x-api-key: your-api-key-here" \
  -H "x-organization-id: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{ "origin": "Barcelona", "destination": "Madrid" }'

# Legacy API endpoints (e.g., /api/facilities)
curl -X GET "https://api.dcycle.io/api/facilities" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "x-organization-id: your-org-id" \
  -H "x-user-id: your-user-id"

Required Headers

New API (Recommended)
Legacy API

Simpler authentication - Only 2 required headers:

Header	Description	Required
`x-api-key`	Your API Key	✅ Yes
`x-organization-id`	Your organization UUID	✅ Yes
`Content-Type`	Content type (for POST/PUT)	Only for POST/PUT

No x-user-id needed! Operations are automatically attributed to the user who created the API key.

Legacy format - 3 required headers:

Header	Description	Required
`Authorization`	Bearer token with your API Key	✅ Yes
`x-organization-id`	Your organization UUID	✅ Yes
`x-user-id`	Your user UUID	✅ Yes
`Content-Type`	Content type (for POST/PUT)	Only for POST/PUT

CLI Authentication

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

The CLI (dc command) supports two authentication methods: interactive login and environment variables. The simplest way to authenticate:

dc auth login

This opens an interactive prompt for your email and password. Your session persists until you explicitly log out.

# Check current authentication status
dc auth status

# Log out
dc auth logout

Environment Variables

For automated scripts and CI/CD pipelines, use environment variables:

export DCYCLE_API_KEY=your_api_key
export DCYCLE_ORG_ID=your_org_id

# Commands use environment automatically
dc vehicle list
dc facility list

Environment variables take precedence over interactive login. This is useful for running scripts with different credentials than your personal account.

Configuration File

The CLI stores configuration in ~/.dcycle/config.yaml:

# ~/.dcycle/config.yaml
host: https://api.dcycle.io
organization_id: your-org-id

You can manage configuration via commands:

# Set active organization
dc org set YOUR_ORG_ID

# Change API environment (advanced)
dc config host https://api.dcycle.io

Learn more about CLI authentication →

MCP Authentication

Coming Soon - The Dcycle MCP Server is in private beta. Contact us for early access.

The MCP (Model Context Protocol) Server uses your API key for authentication with AI assistants like Claude.

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dcycle": {
      "command": "uvx",
      "args": ["dcycle-mcp"],
      "env": {
        "DCYCLE_API_KEY": "your_api_key"
      }
    }
  }
}

Claude Code Configuration

For Claude Code, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "dcycle": {
      "command": "uvx",
      "args": ["dcycle-mcp"],
      "env": {
        "DCYCLE_API_KEY": "your_api_key"
      }
    }
  }
}

Learn more about MCP setup →

JWT Tokens (Web Applications)

JWT tokens are ideal for web and mobile applications acting on behalf of users.

Get a JWT Token

curl -X POST "https://api.dcycle.io/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Extract the token from response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the token in your requests

Include the token in the Authorization header:

curl -X GET "https://api.dcycle.io/api/v1/facilities" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "x-organization-id: your-org-id" \
  -H "x-user-id: your-user-id"

Token Expiration

JWT tokens expire after 1 hour. When a token expires, you’ll get a 401 Unauthorized error. You’ll need to log in again to get a new token.

Tip: Implement automatic refresh in your application to renew tokens before they expire.

Security Best Practices

Never expose your API Key

❌ DON’T save API Keys in source code
❌ DON’T commit them to Git/GitHub
❌ DON’T share them via email or Slack
✅ DO use environment variables
✅ DO use secret managers (AWS Secrets Manager, etc.)

Always use HTTPS

All API requests must use HTTPS. HTTP requests will be rejected.

Rotate your API Keys regularly

Generate new API Keys every 3-6 months
Delete old API Keys immediately after migration
Use different API Keys for different environments (dev, staging, prod)

Environment-specific credentials

Use separate credentials for each environment:

# Development
export DCYCLE_API_KEY=$DEV_API_KEY

# Production
export DCYCLE_API_KEY=$PROD_API_KEY

For CI/CD, store secrets in your pipeline’s secret management (GitHub Secrets, GitLab CI Variables, etc.).

API Key Management

List your API Keys

You can view all your active API Keys at: app.dcycle.io/settings/api

Revoke an API Key

If an API Key has been compromised or you no longer need it:

Go to Organization Settings → API Keys
Find the API Key in the list
Click “Revoke”

Once revoked, the API Key will stop working immediately. This action cannot be undone.

Troubleshooting

Error 401: Unauthorized

Possible causes:

Invalid or revoked API Key
Expired JWT token
Incorrect Authorization header format
Organization doesn’t have API enabled

Solution:

# Verify you're using the correct format
Authorization: Bearer your-api-key-or-jwt-token

Error 403: Forbidden

Possible causes:

User doesn’t belong to the specified organization
Missing x-organization-id header
Organization doesn’t have permissions for that resource

Solution: Verify that the x-organization-id corresponds to your organization.

Next Steps

API Quickstart

Make your first API call

CLI Overview

Get started with the CLI

MCP Setup

Configure AI assistant integration

Introduction

Core Concepts

Support

Authentication

Authentication

API Keys

CLI Login

MCP Setup

API Key Authentication

When to Use API Keys

Get an API Key

User Attribution & Accountability

Using your API Key

Required Headers

CLI Authentication

Environment Variables

Configuration File

MCP Authentication

Claude Desktop Configuration

Claude Code Configuration

JWT Tokens (Web Applications)

Get a JWT Token

Token Expiration

Security Best Practices

API Key Management

List your API Keys

Revoke an API Key

Troubleshooting

Error 401: Unauthorized

Error 403: Forbidden

Next Steps

API Quickstart

CLI Overview

MCP Setup

Introduction

Core Concepts

Support

​Authentication

API Keys

CLI Login

MCP Setup

​API Key Authentication

​When to Use API Keys

​Get an API Key

​User Attribution & Accountability

​Using your API Key

​Required Headers

​CLI Authentication

​Interactive Login

​Environment Variables

​Configuration File

​MCP Authentication

​Claude Desktop Configuration

​Claude Code Configuration

​JWT Tokens (Web Applications)

​Get a JWT Token

​Token Expiration

​Security Best Practices

​API Key Management

​List your API Keys

​Revoke an API Key

​Troubleshooting

​Error 401: Unauthorized

​Error 403: Forbidden

​Next Steps

API Quickstart

CLI Overview

MCP Setup

Authentication

API Key Authentication

When to Use API Keys

Get an API Key

User Attribution & Accountability

Using your API Key

Required Headers

CLI Authentication

Interactive Login

Environment Variables

Configuration File

MCP Authentication

Claude Desktop Configuration

Claude Code Configuration

JWT Tokens (Web Applications)

Get a JWT Token

Token Expiration

Security Best Practices

API Key Management

List your API Keys

Revoke an API Key

Troubleshooting

Error 401: Unauthorized

Error 403: Forbidden

Next Steps