Skip to main content
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.

​
Understanding service user scopes

Enterprise customers can create service users at two levels:
ScopeBase URLUse 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)

  1. Go to Enterprise settings > Service users
  2. Click Create service user
  3. Choose a name (e.g., “Analytics Dashboard”, “Org Provisioning Bot”)
  4. Assign an enterprise role with the permissions your integration needs

​
Organization service user (single-org access)

  1. Go to Settings > Service users within the target organization
  2. Click Create service user
  3. Choose a name and assign an org-level role
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: Generate an API key

  1. After creating the service user, click Generate API key
  2. Copy the key immediately — it starts with cog_ and won’t be shown again
  3. 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 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