external_authentication_required

The external_authentication_required error occurs when a cloud agent task needs access to an external service that the user hasn't authorized, or when the Derp GitHub App doesn't have access to the required repositories.

---

Details

• HTTP Status: 401 Unauthorized
• Retryable: No
• Task State: FAILED

---

When does this occur?

This error is returned when:

• GitHub not connected — Your Derp account is not linked to a GitHub account, but the task's environment includes GitHub repositories
• Repository inaccessible — The Derp GitHub App is not installed on, or does not have access to, one or more repositories required by the task's environment
• Account matching failed — A Slack or Linear user who triggered the task cannot be matched to a Derp account

---

Additional metadata fields

This error includes extra fields beyond the standard response format:

• provider — The external service name (for example, "github", "slack", "linear")
• auth_url — A URL to complete the authorization flow (when available)
• inaccessible_repos — A list of repository names the agent cannot access (when applicable)

---

Example responses

GitHub user not connected

{
  "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/",
  "title": "User is not connected to GitHub",
  "status": 401,
  "instance": "/api/v1/agent/tasks",
  "error": "User is not connected to GitHub. Authorize access here: https://...",
  "retryable": false,
  "provider": "github",
  "auth_url": "https://github.com/login/oauth/authorize?..."
}

Repository inaccessible

{
  "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/",
  "title": "User does not have access to the following repositories in the environment: acme/backend",
  "status": 401,
  "detail": "inaccessible repos: acme/backend",
  "instance": "/api/v1/agent/tasks",
  "error": "User does not have access to the following repositories in the environment: acme/backend (inaccessible repos: acme/backend)",
  "retryable": false,
  "provider": "github",
  "auth_url": "https://github.com/apps/derp-dev/installations/new",
  "inaccessible_repos": ["acme/backend"]
}

Account matching failed (Slack/Linear)

{
  "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/",
  "title": "Unable to locate your Derp account",
  "status": 401,
  "instance": "/api/v1/agent/tasks",
  "error": "Unable to locate your Derp account",
  "retryable": false,
  "provider": "slack"
}

---

How to resolve

GitHub not connected

1. Follow the auth_url in the response to connect your GitHub account to Derp.
2. Complete the OAuth authorization flow.
3. Retry the task.

Repository inaccessible

1. Follow the auth_url to install or reconfigure the Derp GitHub App.
2. Ensure the app has access to all repositories listed in inaccessible_repos.
3. Retry the task.

If you are using an agent API key bound to a cloud agent, ensure the Derp GitHub App is installed on the organization that owns the repositories.

Account matching failed

1. Ensure your Slack or Linear account is associated with the same email as your Derp account.
2. If using Slack, verify the Derp Slack integration is installed in your workspace.
3. Contact your team admin if the issue persists.

---

Related

• Environments — Configuring GitHub repositories for cloud agent environments
• Integrations — Setting up Slack and Linear integrations