Skip to main content

​
Overview

Devin provides multiple API versions with different authentication mechanisms and authorization models. Understanding which API key type to use is crucial for proper integration.

​
API Versions Summary

VersionAuthenticationAuthorization Model
v1Personal or Service API KeysOrg-scoped
v2Personal API KeysEnterprise admin only
v3 (Beta)Service User CredentialsFull RBAC

​
API Key Types

API Key TypePrefixDescription
Personal API Keyapk_user_User-Org scoped keys that inherit individual user permissions
Service API Keyapk_Organization-scoped service keys for automation
Service User Credentialcog_Enterprise/Organization service user credentials with RBAC

​
Personal API Keys

Personal API keys are tied to individual user accounts and scoped to an org. They inherit the permissions of that user. Where to generate:
  • Navigate to Settings > API Keys in any sub-organization
  • Click “Generate New API Key”
  • Copy and securely store the key (it will only be shown once)
Supported API versions:
  • v1: Yes - inherits user’s org-level permissions
  • v2: Yes - only for users with Enterprise Admin role
  • v3: No - use Service User Credentials instead
Recommended use cases:
  • Personal automation scripts
  • Development and testing
  • User-specific integrations
Security considerations:
  • Keys are scoped to the user’s permissions
  • Revoking a user’s access automatically invalidates their API keys
  • Keys should be rotated regularly

​
Service API Keys (Organization-scoped)

Service API keys can be generated within sub-organizations under certain conditions. Where to generate: Supported API versions:
  • v1: Yes - scoped to the organization
  • v2: No - not supported
  • v3: No - use Service User Credentials instead
Recommended use cases:
  • Organization-level automation
  • CI/CD pipelines scoped to specific teams
  • Shared tooling within a sub-organization

​
Service User Credentials (v3 Only)

Service users are dedicated accounts with specific roles and permissions, designed for API-based automation with full RBAC support. Where to generate:
  • Navigate to Enterprise Settings > Service Users
  • Click “Create Service User”
  • Assign appropriate roles (Enterprise Admin, Org Admin, Org Member, etc.)
  • Generate API key for the service user
Service user types:
  • Enterprise Service Users: Can access multiple organizations based on assigned roles
  • Organization Service Users: Scoped to specific organizations with org-level roles
Supported API versions:
  • v1: No - not available
  • v2: No - not available
  • v3: Yes - full RBAC support
Recommended use cases:
  • Production automation with granular permissions
  • Multi-organization workflows
  • Compliance-sensitive integrations requiring audit trails
  • Long-lived integrations with specific permission scopes
Security considerations:
  • Service users appear in audit logs separately from human users
  • Permissions can be precisely controlled via RBAC
  • Keys can be rotated without affecting human user accounts
  • Ideal for principle of least privilege

​
Authentication Methods

​
Bearer Token Authentication

All Devin APIs use Bearer token authentication. Include your API key in the Authorization header: 
Authorization: Bearer your_api_key_here

​
Example Requests

v1 API Example: 
curl -X POST "https://api.devin.ai/v1/sessions" \
  -H "Authorization: Bearer YOUR_V1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a simple Python script"
  }'
v2 Enterprise API Example: 
curl -X GET "https://api.devin.ai/v2/enterprise/organizations" \
  -H "Authorization: Bearer YOUR_V2_ENTERPRISE_ADMIN_KEY"
v3 API Example (Beta): 
curl -X GET "https://api.devin.ai/v3beta1/enterprise/organizations" \
  -H "Authorization: Bearer YOUR_V3_SERVICE_USER_KEY"

​
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 v3 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 wrong API version for your key type (e.g., personal key with v3)
  • Attempting to access resources outside your scope
Solution:
  • For v2: Ensure you have Enterprise Admin role
  • For v3: Use a service user credential with appropriate roles
  • For v1: 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 matches the API version you’re using and that the resource exists.

​
Next Steps