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

Never put an API key in code that runs in a browser or a mobile app, in a URL or in your logs: whoever reads it can act as you.

Get an API Key

Go to app.dcycle.io

Open Company settings → API Keys

Click your name at the bottom of the sidebar, then Company settings, then API Keys. Only an admin of the organization can create keys. If API Keys is not there, the API is not enabled for your organization yet: ask your Dcycle contact.

Generate a new key

Click Generate new key (or Create one to get started if the organization has no key yet).

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

Copy your organization ID

In Company settings → Organization info, click Copy organization ID. Every request sends it in x-organization-id.

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

A key has the same access as the person who created it, in the organization and in the subsidiaries where they are a member: there are no read-only or limited keys, and keys have no name. To test an integration, use a key of a test organization rather than one of your production organization.

Using your API Key

Send your API key in the x-api-key header and your organization ID in x-organization-id, on /v1 and /v2 alike. On api.dcycle.io, Authorization: Bearer is only for JWT tokens: an API key sent there is rejected, except on the legacy /api/v1/... routes. (The MCP server is a separate service and takes the key as a Bearer token.) This call lists the ingest jobs of your organization and its group, so it is a safe way to check your credentials:

x-api-key (v1 and v2, recommended)
Legacy /api/v1 routes (not for new integrations)

curl "https://api.dcycle.io/v2/ingest-jobs" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import os

import requests

headers = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_ORG_ID"],
}

response = requests.get("https://api.dcycle.io/v2/ingest-jobs", headers=headers, timeout=30)
response.raise_for_status()
print(response.json()["total"])

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

const response = await fetch('https://api.dcycle.io/v2/ingest-jobs', { headers });
const data = await response.json();
console.log(data.total);

Bulk writes add an Idempotency-Key header. The Quickstart walks through a complete write: create a facility, send it a waste and follow its ingest job.

Only the legacy /api/v1/... routes take the key this way, and they remain for existing integrations: don’t use them in new ones. They require x-user-id, which makes the request act as that member of the organization, so whoever holds the key can act as any member.

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

import requests

# Legacy format - 3 headers required
headers = {
    "Authorization": f"Bearer {api_key}",
    "x-organization-id": org_id,
    "x-user-id": user_id
}

response = requests.get(
    "https://api.dcycle.io/api/v1/facilities",
    headers=headers
)

// Legacy format - 3 headers required
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'x-organization-id': orgId,
  'x-user-id': userId
};

fetch('https://api.dcycle.io/api/v1/facilities', { headers })
  .then(res => res.json())
  .then(data => console.log(data));

Required Headers

x-api-key (v1 and v2, recommended)
Legacy /api/v1 routes (not for new integrations)

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`	`application/json`	Only with a body
`Idempotency-Key`	A value of yours, unique per batch: a retry with the same key never writes twice	For v2 bulk writes (a body with `records` or `ids`)

Don’t send x-user-id. Without it, every request acts as the person who created the API key. With it, the request can act as another member of the organization.

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 (dcy command) supports two authentication methods: interactive login and environment variables. The simplest way to authenticate:

dcy auth login

This opens your browser to the Dcycle sign-in page. You complete the full authentication flow in the browser (email, password, MFA, SSO) and the CLI receives the session automatically. Use --no-browser to authenticate directly in the terminal instead:

dcy auth login --no-browser

Your session persists until you explicitly log out.

# Check current authentication status
dcy auth status

# Log out
dcy 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
dcy vehicle list
dcy 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 ~/.config/dcycle/v2/config.yaml:

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

You can manage configuration via commands:

# Set active organization
dcy org set YOUR_ORG_ID

# Change API environment
dcy config host set prod

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 is hosted at https://mcp.dcycle.io/mcp. AI assistants like Claude sign in with your Dcycle account (OAuth, in the browser), or send an API key as Authorization: Bearer dcy_<your_api_key> (the dcy_ prefix is required).

Claude Code

# Sign in with your Dcycle account on first use
claude mcp add --transport http dcycle https://mcp.dcycle.io/mcp

# Or with an API key
claude mcp add --transport http dcycle https://mcp.dcycle.io/mcp --header "Authorization: Bearer dcy_<your_api_key>"

For Claude Desktop, ChatGPT and other clients, see the MCP quickstart.

dcycle-mcp is not published by Dcycle on PyPI: do not install it with pip or run it with uvx, since whatever that name installs is not Dcycle’s.

Learn more about MCP setup →

JWT Tokens (Dcycle Apps)

JWT tokens are what Dcycle’s own apps and the CLI use: a token comes from a person signing in to Dcycle, and the requests made with it act as that person. Integrations use API keys instead. A JWT goes in the Authorization header, with the organization in x-organization-id:

curl -X GET "https://api.dcycle.io/v2/ingest-jobs" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "x-organization-id: your-org-id"

A token expires: the API then answers 401 and the app signs in again.

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
❌ DON’T put them in code that runs in a browser or a mobile app, in URLs or in logs
✅ 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
Revoke old API keys as soon as your integrations use the new ones

Keep test and production apart

Every key of an organization has the full access of the person who created it: there are no read-only or limited keys. To test an integration, use a key of a test organization, never one of your production organization:

# Test organization
export DCYCLE_API_KEY=$TEST_ORG_API_KEY

# Production organization
export DCYCLE_API_KEY=$PROD_ORG_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

The active API keys of your organization are listed in Company settings → API Keys. A key is never shown again after it is created: the list shows a short reference for each one (the end of its id, not of the key), when it was created and by whom. If you don’t know which key leaked, revoke them all and create a new one.

Revoke an API Key

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

Go to Company settings → API Keys
Find the API key in the list
Click its trash icon and confirm

Once revoked, the API key stops working immediately. This action cannot be undone.

Webhook endpoints belong to the organization, not to a key: they keep receiving events after the key that registered them is revoked. Review them in Company settings → Webhooks or with List Webhook Endpoints.

Troubleshooting

Error 401: Unauthorized

Possible causes:

Invalid or revoked API key (INVALID_API_KEY)
A key of another organization (API_KEY_ORG_MISMATCH): x-organization-id must be the key’s organization or one of its subsidiaries
API key sent in Authorization: Bearer instead of x-api-key, or an Authorization header without a valid token sent along with x-api-key: it is checked first, so the request fails even with a valid key
Expired JWT token

Solution:

# An API key goes in x-api-key
x-api-key: your-api-key
x-organization-id: your-org-id

# On api.dcycle.io /v1 and /v2, Authorization: Bearer is only for a JWT token
Authorization: Bearer your-jwt-token

A 401 caused by the API key names its cause in code (see Errors). A rejected Authorization header answers {"detail": "..."} instead, for example INVALID_OR_EXPIRED_TOKEN (see Errors that are not problem details).

Error 403: Forbidden

Possible causes:

LOGGED_USER_NOT_MEMBER: the person who created the key is not a member of the organization in x-organization-id
ORG_ADMIN_REQUIRED: the action needs an organization admin, for example managing webhook endpoints

Error 400: Bad Request

ORGANIZATION_ID_REQUIRED: the x-organization-id header is missing

Next Steps

API Quickstart

Make your first API call

CLI Overview

Get started with the CLI

MCP Setup

Configure AI assistant integration

Introduction

Security & Compliance

Core Concepts

Support

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 Code

JWT Tokens (Dcycle Apps)

Security Best Practices

API Key Management

List your API Keys

Revoke an API Key

Troubleshooting

Error 401: Unauthorized

Error 403: Forbidden

Error 400: Bad Request

Next Steps

API Quickstart

CLI Overview

MCP Setup

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 Code

​JWT Tokens (Dcycle Apps)

​Security Best Practices

​API Key Management

​List your API Keys

​Revoke an API Key

​Troubleshooting

​Error 401: Unauthorized

​Error 403: Forbidden

​Error 400: Bad Request

​Next Steps

API Quickstart

CLI Overview

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 Code

JWT Tokens (Dcycle Apps)

Security Best Practices

API Key Management

List your API Keys

Revoke an API Key

Troubleshooting

Error 401: Unauthorized

Error 403: Forbidden

Error 400: Bad Request

Next Steps