Skip to main content
Service users are dedicated bot accounts for API access with role-based permissions. This is the recommended authentication method for all new integrations.

​
How it works

  1. Create a service user in Settings > Service users
  2. Assign a role that controls which endpoints the service user can access
  3. Generate an API key (starts with cog_)
  4. Include the key in the Authorization header of every request
curl -X POST "https://api.devin.ai/v3/organizations/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a simple Python script"}'

​
Service user scopes

ScopeCreated inAPI accessUse case
OrganizationSettings > Service users/v3/organizations/*Session management, knowledge, playbooks, secrets
EnterpriseEnterprise settings > Service users/v3/enterprise/* + /v3/organizations/*Cross-org management, analytics, audit logs, billing
Organization-scoped service users can call endpoints without specifying {org_id} in the URL — it’s automatically resolved from the credential.

​
Session attribution with create_as_user_id

Service users are separate identities from human users. By default, sessions created by a service user are attributed to the service user itself. To create sessions on behalf of a specific user, pass the create_as_user_id parameter when creating a session. The session will appear in that user’s session list and count toward their usage. This requires the ImpersonateOrgSessions permission on the service user’s role.
Migrating from personal API keys? Personal API keys (v1/v2) automatically created sessions as your user. With service users, use create_as_user_id for the same behavior — with added RBAC, audit trails, and centralized key management. See the API Overview for an example.

​
Key properties

  • Keys start with cog_ and are shown only once at creation time
  • Service users appear separately from human users in audit logs
  • Permissions are controlled via RBAC — assign only what the integration needs
  • Enterprise service users inherit org-level permissions across all organizations
For detailed setup instructions, see the Teams quick start or Enterprise quick start.

​
Legacy API keys

Legacy API keys are being deprecated in favor of service users. We recommend migrating existing integrations to service users. See the migration guide.
Legacy API keys are used with the v1 and v2 APIs. They continue to work during the deprecation period but do not support new features like RBAC, session attribution, or cursor-based pagination.
Key typePrefixUsed withDescription
Personal API keyapk_user_v1, v2Tied to a user account, inherits user permissions
Service API keyapk_v1Organization-scoped, for automation
Where to generate: Settings > API Keys

​
Bearer token authentication

All Devin APIs use Bearer token authentication. Include your key in the Authorization header: 
Authorization: Bearer your_api_key_here
This applies to both service user credentials and legacy API keys.

​
Security best practices

Never share API keys in publicly accessible areas such as GitHub repositories, client-side code, or logs.
  1. Store keys securely: Use environment variables or secret management systems
  2. Rotate keys regularly: Generate new keys and revoke old ones periodically
  3. Use service users for automation: Prefer service users over personal keys for production
  4. Apply least privilege: Grant only the minimum permissions required
  5. Monitor usage: Review audit logs for unexpected API activity
  6. Revoke compromised keys immediately: If a key is exposed, revoke it and generate a new one

​
Troubleshooting

​
401 Unauthorized

Possible causes:
  • Invalid or expired API key
  • Missing Authorization header
  • Incorrect Bearer token format
Solution: Verify your API key is correct and properly formatted in the Authorization header.

​
403 Forbidden

Possible causes:
  • API key doesn’t have required permissions
  • Using the wrong key type for the endpoint (e.g., legacy key with v3 endpoints)
  • Attempting to access resources outside your scope
Solution:
  • Ensure your service user has the correct role and permissions
  • For legacy v2 endpoints: ensure you have the Enterprise Admin role
  • For legacy v1 endpoints: verify you have access to the organization

​
404 Not Found

Possible causes:
  • Incorrect API endpoint URL
  • Resource doesn’t exist or you don’t have access
Solution: Verify the endpoint URL and that the resource exists.

​
Next steps