PipesHub OAuth API
OAuth 2.0 token exchange for third-party authentication providers
OAuth 2.0 token exchange for third-party authentication providers
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pipeshub:pipeshub-oauth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: PipesHub OAuth API
description: Unified API documentation for PipesHub services.
version: 1.0.0
contact:
name: API Support
email: support@pipeshub.com
servers:
- url: '{instance_url}/api/v1'
description: Base API URL
variables:
instance_url:
default: https://app.pipeshub.com
description: Base server URL (without /api/v1)
- url: '{instance_url}'
description: Root URL (used for MCP endpoints mounted at /mcp)
variables:
instance_url:
default: https://app.pipeshub.com
description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: OAuth
description: OAuth 2.0 token exchange for third-party authentication providers
paths:
/userAccount/oauth/exchange:
post:
tags:
- OAuth
summary: Exchange OAuth authorization code for tokens
description: 'Exchange an OAuth authorization code for access and ID tokens.
Used after the OAuth authorization flow redirects back to the application.
**Supported Providers:**
- Generic OAuth 2.0 providers configured in org settings
**Flow:**
1. User is redirected to OAuth provider''s authorization URL
2. User authorizes and is redirected back with a code
3. This endpoint exchanges the code for tokens
4. Tokens can then be used with the `/userAccount/authenticate` endpoint'
operationId: exchangeOAuthCode
security: []
requestBody:
description: Request payload
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthExchangeRequest'
required: true
responses:
'200':
description: Tokens retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthExchangeResponse'
'400':
description: 'Bad request. Possible causes: missing required parameters (code, provider, redirectUri),
no organization found in the system, OAuth not configured (missing tokenEndpoint or
clientSecret), token exchange HTTP error from the provider, or email not present in
the OAuth provider''s userInfo response.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Failed to fetch user information from the OAuth provider using the exchanged access token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: User account not found and JIT provisioning is disabled — contact your administrator
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ErrorResponse:
type: object
additionalProperties: false
description: 'Standard error envelope returned by all errors routed through `ErrorMiddleware`.
Applies to all `BaseError` subclasses including `HttpError`, `ValidationError`, and others.
The `code` field is a machine-readable string identifying the error type (e.g.
`HTTP_UNAUTHORIZED`, `HTTP_NOT_FOUND`, `VALIDATION_ERROR`, `INTERNAL_ERROR`).
'
properties:
error:
type: object
additionalProperties: false
required:
- code
- message
properties:
requestId:
type: string
description: 'Identifier for this request, echoed so a bug report can quote it.
Absent when the request never reached the middleware that assigns one.
'
code:
type: string
description: 'Machine-readable error code. For application errors it takes the form `HTTP_<VARIANT>`
For unhandled runtime errors (e.g. database unavailable) it is `INTERNAL_ERROR`.
'
example: HTTP_BAD_REQUEST
message:
type: string
description: Human-readable description of the error
example: Admin access required
metadata:
type: object
description: Additional context (only present in development environments)
additionalProperties: true
required:
- error
OAuthExchangeResponse:
type: object
additionalProperties: false
description: OAuth token response
properties:
access_token:
type: string
description: OAuth access token
id_token:
type: string
description: OAuth ID token (JWT)
token_type:
type: string
example: Bearer
expires_in:
type: integer
description: Token expiry in seconds
required:
- access_token
- token_type
OAuthExchangeRequest:
type: object
additionalProperties: false
description: Request to exchange OAuth authorization code for tokens
properties:
code:
type: string
description: OAuth authorization code
provider:
type: string
description: OAuth provider name
redirectUri:
type: string
format: uri
description: Redirect URI used in authorization request
required:
- code
- provider
- redirectUri
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'JWT Bearer token for authenticated requests.
A personal access token (see the **Personal Access Tokens** tag) is a
`phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.
The prefix is display-only, added for secret-scanner detectability; the
gateway strips it before verifying the token, so send it exactly as
issued, prefix included.
'
scopedToken:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Scoped JWT token for service-to-service authentication.
Format: "Bearer {scoped_token}"
Required scopes vary by endpoint.
'
oauth2:
type: oauth2
description: 'OAuth 2.0 authentication with fine-grained scopes.
Supports authorization_code (with PKCE) and client_credentials flows.
OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.
For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.
'
flows:
authorizationCode:
authorizationUrl: /api/v1/oauth2/authorize
tokenUrl: /api/v1/oauth2/token
refreshUrl: /api/v1/oauth2/token
scopes:
openid: OpenID Connect authentication
profile: User profile information
email: User email address
offline_access: Offline access (refresh tokens)
org:read: Read organization information
org:write: Update organization settings
org:admin: Full organization administration
user:read: Read user profiles
user:write: Update user profiles
user:invite: Invite new users
user:delete: Delete users
usergroup:read: Read user groups
usergroup:write: Create and manage user groups
team:read: Read team information
team:write: Create and manage teams
kb:read: Read knowledge bases and records
kb:write: Create and update knowledge bases
kb:delete: Delete knowledge bases and records
kb:upload: Upload files to knowledge bases
semantic:read: Read semantic search results and history
semantic:write: Execute semantic search
semantic:delete: Delete semantic search history
conversation:read: Read conversations
conversation:write: Create and manage conversations
conversation:chat: Send messages in conversations
project:read: Read projects and their conversations
project:write: Create and manage projects
project:delete: Delete projects
agent:read: Read AI agents
agent:write: Create and manage AI agents
agent:execute: Execute AI agents
connector:read: Read connector configurations
connector:write: Create and update connectors
connector:sync: Trigger connector synchronization
connector:delete: Delete connectors
config:read: Read system configuration
config:write: Update system configuration
crawl:read: Read crawling jobs
crawl:write: Create and manage crawling jobs
crawl:delete: Delete crawling jobs
clientCredentials:
tokenUrl: /api/v1/oauth2/token
scopes:
openid: OpenID Connect authentication
profile: User profile information
email: User email address
offline_access: Offline access (refresh tokens)
org:read: Read organization information
org:write: Update organization settings
org:admin: Full organization administration
user:read: Read user profiles
user:write: Update user profiles
user:invite: Invite new users
user:delete: Delete users
usergroup:read: Read user groups
usergroup:write: Create and manage user groups
team:read: Read team information
team:write: Create and manage teams
kb:read: Read knowledge bases and records
kb:write: Create and update knowledge bases
kb:delete: Delete knowledge bases and records
kb:upload: Upload files to knowledge bases
semantic:write: Execute semantic search
semantic:read: Read semantic search results and history
semantic:delete: Delete semantic search history
conversation:read: Read conversations
conversation:write: Create and manage conversations
conversation:chat: Send messages in conversations
project:read: Read projects and their conversations
project:write: Create and manage projects
project:delete: Delete projects
agent:read: Read AI agents
agent:write: Create and manage AI agents
agent:execute: Execute AI agents
connector:read: Read connector configurations
connector:write: Create and update connectors
connector:sync: Trigger connector synchronization
connector:delete: Delete connectors
config:read: Read system configuration
config:write: Update system configuration
crawl:read: Read crawling jobs
crawl:write: Create and manage crawling jobs