Quick start: Enterprise

This guide walks you through setting up API access for enterprise organizations with custom roles, RBAC, and multi-organization support.

If you’re on a teams plan with a single organization and don’t need custom roles, the Teams quick start is simpler.

If you are a Devin Enterprise customer with a dedicated deployment, you will need to replace api.devin.ai in all API URLs with your organization’s custom API domain (e.g., api.your-company.devinenterprise.com). Contact your Devin administrator or Cognition support if you are unsure of your API domain.

Understanding service user scopes

Enterprise customers can create service users at two levels:

Scope	Base URL	Use case
Enterprise	`/v3/enterprise/*`	Cross-org management, analytics, audit logs, member management
Organization	`/v3/organizations/{org_id}/*`	Sessions, knowledge, playbooks, secrets within a single org

An enterprise service user with enterprise-level permissions automatically inherits the corresponding org-level permissions across all organizations.

Step 1: Create a service user

Enterprise service user (cross-org access)

Go to Enterprise settings > Devin API and open the Service users tab
Click Provision > Enterprise service user
Choose a display name (e.g., “Analytics Dashboard”, “Org Provisioning Bot”)
Assign an enterprise role with the permissions your integration needs, and choose an expiration

Organization service user (single-org access)

Go to Settings > Devin API within the target organization and open the Service users tab
Click Provision service user
Choose a display name, assign an org-level role, and choose an expiration

You can also provision an organization service user from Enterprise settings > Devin API by clicking Provision > Organization service user and selecting the target organization.

Follow the principle of least privilege: create org-scoped service users when your integration only needs access to one organization. Use enterprise service users only for cross-org workflows.

Step 2: Copy your API key

After you provision the service user, its API key is shown in a dialog
Copy the key immediately — it starts with cog_ and won’t be shown again
Store it securely as an environment variable:

export DEVIN_API_KEY="cog_your_key_here"

Step 3: Make your first API call

Enterprise endpoint example

List all organizations in your enterprise:

curl "https://api.devin.ai/v3/enterprise/organizations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Organization endpoint example

Create a Devin session in a specific org:

export DEVIN_ORG_ID="your_org_id"

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Implement the feature described in JIRA-123"}'

Permissions and RBAC

Every API endpoint except GET /v3/self is gated by a specific permission. The required permission is documented on each endpoint’s API reference page. Permissions are split into two scopes:

Enterprise permissions — control /v3/enterprise/* endpoints (e.g., ManageOrganizations, ManageBilling, ViewAccountMetrics)
Organization permissions — control /v3/organizations/{org_id}/* endpoints (e.g., UseDevinSessions, ManageOrgSecrets, ManageOrgPlaybooks)

An enterprise service user with an enterprise-level permission automatically inherits the corresponding org-level permission across all organizations. For example, ViewAccountSessions grants ViewOrgSessions in every org. For the full permissions reference, see the permissions and RBAC documentation.

Common enterprise workflows

Monitor consumption across orgs

# Get daily consumption breakdown (uses Unix timestamps — example: Jan 1 to Jan 31, 2025)
curl "https://api.devin.ai/v3/enterprise/consumption/daily?time_after=1735689600&time_before=1738368000" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Audit log retrieval

curl "https://api.devin.ai/v3/enterprise/audit-logs" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Manage users across organizations

# List enterprise users
curl "https://api.devin.ai/v3/enterprise/members/users" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

# List users in a specific org
curl "https://api.devin.ai/v3/enterprise/organizations/$DEVIN_ORG_ID/members/users" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Next steps

Browse the full API permissions reference
Learn about authentication in depth
Set up pagination for large result sets
Review the migration guide if you’re moving from v1/v2

Getting Started

Concepts

Agent Lifecycle

Context Management

Environment Management

Automation

Integrations

Analytics

Observability

Devin for Security

Infrastructure

Identity & Access

Configuration

Legacy API v1

Legacy API v2

Quick start: Enterprise

Understanding service user scopes

Step 1: Create a service user

Enterprise service user (cross-org access)

Organization service user (single-org access)

Step 2: Copy your API key

Step 3: Make your first API call

Enterprise endpoint example

Organization endpoint example

Permissions and RBAC

Common enterprise workflows

Monitor consumption across orgs

Audit log retrieval

Manage users across organizations

Next steps

​Understanding service user scopes

​Step 1: Create a service user

​Enterprise service user (cross-org access)

​Organization service user (single-org access)

​Step 2: Copy your API key

​Step 3: Make your first API call

​Enterprise endpoint example

​Organization endpoint example

​Permissions and RBAC

​Common enterprise workflows

​Monitor consumption across orgs

​Audit log retrieval

​Manage users across organizations

​Next steps

Understanding service user scopes

Step 1: Create a service user

Enterprise service user (cross-org access)

Organization service user (single-org access)

Step 2: Copy your API key

Step 3: Make your first API call

Enterprise endpoint example

Organization endpoint example

Permissions and RBAC

Common enterprise workflows

Monitor consumption across orgs

Audit log retrieval

Manage users across organizations

Next steps