Skip to main content
The Devin API uses a principal + token model. A principal is who you are (your identity), and a token is how you prove it (your credential). Understanding this distinction is the key to choosing the right authentication method for your use case.

​
Principals & tokens

PrincipalTokenDescription
Service User (non-human)Service User API KeyFor automated integrations and CI/CD pipelines
User (human)Personal Access Token (PAT)For human programmatic access under your own identity
All API credentials use the cog_ prefix format. Include your token in the Authorization header of every request: 
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer cog_your_token_here"
The key distinction is which principal the token authenticates as:
  • A Service User API Key authenticates as the service user — the service user’s identity, permissions, and org memberships apply.
  • A Personal Access Token authenticates as the human user who created it — that user’s identity, permissions, and org memberships apply.
Service users are non-human accounts designed for API integrations. They can be assigned specific permissions via RBAC and added to organizations independently of human users.

​
How it works

  1. Create a service user in Settings > Service users (organization) or Enterprise settings > Service users (enterprise)
  2. Assign a role that controls which endpoints the service user can access
  3. Generate an API key — the key starts with cog_ and is shown only once at creation
  4. Use the key in the Authorization header of every API request
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": "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
Find your organization ID on the Settings > Service Users page.

​
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.

​
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.

​
Personal access tokens (closed beta)

Personal Access Tokens are currently in closed beta and are feature-flagged. Contact support for access. PATs are not available for SSO/enterprise accounts.
Personal Access Tokens (PATs) allow human users to authenticate programmatically under their own identity. When you use a PAT, the API sees you — your permissions, your org memberships, and your audit trail. This is useful when you want to make API calls as yourself (e.g., personal scripts, local tooling) rather than through a shared service user. For more details, see Personal Access Tokens.

​
Legacy authentication (deprecated)

Legacy API keys are deprecated. Use API v3 with service user authentication. 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

​
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