> ## Documentation Index
> Fetch the complete documentation index at: https://pipedream.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List user accounts
> List all connected accounts for a specific external user. Equivalent to GET /accounts with external_user_id filter but uses path-based routing.
To retrieve credentials for OAuth apps (Slack, Google Sheets, etc), **the connected account must be using [your own OAuth client](/connect/managed-auth/oauth-clients/#using-a-custom-oauth-client)**.
Never return user credentials to the client
## OpenAPI
````yaml get /v1/connect/{project_id}/users/{external_user_id}/accounts
openapi: 3.0.4
info:
version: 2.0.0
title: Pipedream REST API
servers:
- url: https://api.pipedream.com
security: []
paths:
/v1/connect/{project_id}/users/{external_user_id}/accounts:
parameters:
- name: project_id
in: path
required: true
description: The project ID, which starts with `proj_`.
schema:
type: string
pattern: ^proj_[a-zA-Z0-9]+$
x-fern-sdk-variable: project_id
- name: external_user_id
in: path
required: true
schema:
type: string
get:
summary: List accounts for external user
description: >-
List all connected accounts for a specific external user. Equivalent to
GET /accounts with external_user_id filter but uses path-based routing.
operationId: listUserAccounts
parameters:
- name: x-pd-environment
in: header
required: true
description: The environment in which the server client is running
schema:
$ref: '#/components/schemas/ProjectEnvironment'
- name: include_credentials
in: query
required: false
schema:
type: boolean
- name: app
in: query
required: false
schema:
type: string
responses:
'200':
description: accounts listed
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Account'
'429':
description: too many requests
headers:
Retry-After:
description: Number of seconds until the rate limit resets
schema:
type: integer
X-RateLimit-Limit:
schema:
type: integer
description: The rate limit threshold
X-RateLimit-Remaining:
schema:
type: integer
description: Number of requests remaining (always 0 when throttled)
X-RateLimit-Reset:
schema:
type: integer
description: Unix timestamp when the rate limit resets
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Throttled
security:
- ConnectToken: []
- OAuth2: []
x-codeSamples:
- lang: java
label: Java SDK
source: >
package com.example.usage;
import com.pipedream.api.BaseClient;
import
com.pipedream.api.resources.accounts.requests.AccountsListByExternalUserRequest;
public class Example {
public static void main(String[] args) {
BaseClient client = BaseClient.withCredentials("", "")
.projectId("YOUR_PROJECT_ID")
.build()
;
client.accounts().listByExternalUser(
"external_user_id",
AccountsListByExternalUserRequest
.builder()
.includeCredentials(true)
.app("app")
.build()
);
}
}
- lang: python
label: Python SDK
source: |
from pipedream import Pipedream
client = Pipedream(
project_id="YOUR_PROJECT_ID",
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
)
client.accounts.list_by_external_user(
external_user_id="external_user_id",
include_credentials=True,
app="app",
)
- lang: typescript
label: TypeScript SDK
source: |
import { PipedreamClient } from "@pipedream/sdk";
const client = new PipedreamClient({
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
projectEnvironment: "YOUR_PROJECT_ENVIRONMENT",
projectId: "YOUR_PROJECT_ID"
});
await client.accounts.listByExternalUser("external_user_id", {
includeCredentials: true,
app: "app"
});
components:
schemas:
ProjectEnvironment:
type: string
description: The environment in which the server client is running
enum:
- development
- production
Account:
type: object
description: End user account data, returned from the API.
required:
- id
properties:
id:
$ref: '#/components/schemas/AccountId'
name:
type: string
description: The custom name of the account if set.
nullable: true
external_id:
type: string
description: The external ID associated with the account.
healthy:
type: boolean
description: >-
Indicates if the account is healthy. Pipedream will periodically
retry token refresh and test requests for unhealthy accounts
dead:
type: boolean
nullable: true
description: Indicates if the account is no longer active
app:
$ref: '#/components/schemas/App'
created_at:
type: string
description: >-
The date and time the account was created, an ISO 8601 formatted
string
format: date-time
updated_at:
type: string
description: >-
The date and time the account was last updated, an ISO 8601
formatted string
format: date-time
authorized_scopes:
type: array
items:
type: string
description: >-
The OAuth scopes effectively granted to this account. Empty for
non-OAuth apps.
credentials:
type: object
description: >-
The credentials associated with the account, if the
`include_credentials` parameter was set to true in the request (only
applicable for BYOA apps). In addition to the well-known OAuth
fields listed below, this object may contain app-specific custom
fields (e.g. `base_url`).
nullable: true
additionalProperties: true
properties:
oauth_client_id:
type: string
description: The OAuth client ID for the app, if applicable
oauth_access_token:
type: string
description: The OAuth access token
oauth_refresh_token:
type: string
description: The OAuth refresh token
oauth_uid:
type: string
description: The unique OAuth user identifier
oauth_signer_uri:
type: string
description: The OAuth signer URI, if the app uses a custom OAuth signer
expires_at:
type: string
description: >-
The date and time the account's credentials expiration, an ISO 8601
formatted string
format: date-time
error:
type: string
description: >-
The error message if the account is unhealthy or dead, null
otherwise
nullable: true
last_refreshed_at:
type: string
description: >-
The date and time the account was last refreshed, an ISO 8601
formatted string
format: date-time
nullable: true
next_refresh_at:
type: string
description: >-
The date and time the account will next be refreshed, an ISO 8601
formatted string
format: date-time
nullable: true
AccountId:
type: string
description: The unique ID of the account.
pattern: ^apn_[a-zA-Z0-9]+$
App:
type: object
description: Response object for a Pipedream app's metadata
required:
- name_slug
- name
- img_src
- custom_fields_json
- categories
- featured_weight
- scope_profiles
properties:
id:
type: string
description: ID of the app. Only applies for OAuth apps.
nullable: true
name_slug:
type: string
description: >-
The name slug of the target app (see
https://pipedream.com/docs/connect/quickstart#find-your-apps-name-slug)
name:
type: string
description: The human-readable name of the app
auth_type:
$ref: '#/components/schemas/AppAuthType'
description:
type: string
description: A short description of the app
nullable: true
img_src:
type: string
description: The URL to the app's logo
custom_fields_json:
type: string
description: A JSON string representing the custom fields for the app
nullable: true
categories:
type: array
items:
type: string
description: Categories associated with the app
featured_weight:
type: number
description: >-
A rough directional ordering of app popularity, subject to changes
by Pipedream
scope_profiles:
type: array
description: >-
Named subsets of the app's OAuth scopes that may be requested when
users connect their accounts (via the `oauth_scope_profile`
parameter). Empty for apps that don't define any.
items:
type: object
required:
- name
- scopes
properties:
name:
type: string
enum:
- read_only
- read_write
- admin
description: >-
The profile name. Pass this back as `oauth_scope_profile` when
starting the OAuth flow for this app.
scopes:
type: array
items:
type: string
description: >-
The actual OAuth scopes of the upstream API that the user will
be asked to authorize when this profile is selected.
AppAuthType:
type: string
enum:
- keys
- oauth
- none
description: The authentication type used by the app
nullable: true
securitySchemes:
ConnectToken:
description: >-
A short-lived Connect token for client-side requests on behalf of an end
user. Generate one via the Create Connect token endpoint.
type: http
scheme: bearer
bearerFormat: ^ctok_[0-9a-f]{32}$
OAuth2:
description: >-
A short-lived OAuth access token for server-side requests. Generate one
via the Generate OAuth Token flow or automatically when initializing the
SDK client.
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.pipedream.com/v1/oauth/token
scopes:
'*': Full access to every OAuth-protected endpoint.
connect:*: >-
Full access to all Connect API endpoints (components, projects,
triggers, accounts, etc.).
connect:actions:*: Full access to Connect actions.
connect:triggers:*: Full access to Connect triggers.
connect:accounts:read: List and fetch Connect accounts for an external user.
connect:accounts:write: Create or remove Connect accounts.
connect:deployed_triggers:read: >-
Read deployed triggers and related data like events, pipelines and
webhooks.
connect:deployed_triggers:write: Modify or delete deployed triggers.
connect:users:read: List and fetch external users
connect:users:write: Delete external users.
connect:projects:read: List and fetch projects owned by the workspace.
connect:projects:write: Create, update, or delete projects owned by the workspace.
connect:usage:read: List Connect usage records for a time window.
connect:tokens:create: Create Connect session tokens.
connect:proxy: Invoke the Connect proxy.
connect:workflow:invoke: Invoke Connect workflows on behalf of a user.
````