Sign in

v10

latestOpenAPI 3.0.0raw.githubusercontent.com2026-07-0582185581.9 KB
OAuth Apps

Create OAuth app

Register a new OAuth app for the organization. Any authenticated org member may create apps; the creator is recorded as the app's owner and is the only user who can subsequently read, update, suspend, activate, regenerate the secret of, or delete it.

The clientSecret is returned in this response only — it is stored hashed server-side and cannot be retrieved later. Persist it before exiting the create flow; if it is ever lost, rotate via POST /oauth-clients/{appId}/regenerate-secret.

allowedScopes is validated against the caller's role-aware scope set (see GET /oauth-clients/scopes). Org admins may include admin-only scopes; non-admins requesting a restricted scope receive 400.

All /oauth-clients/* routes share a per-user rate limiter (default 1000 req/min, configurable via the MAX_OAUTH_CLIENT_REQUESTS_PER_MINUTE env var).

post/oauth-clients

Request body

namestring required

App name (displayed to users during authorization)

descriptionstring

App description

redirectUrisstring[]

Allowed redirect URIs (max 10). Required when an effective grant list includes authorization_code (including the default when allowedGrantTypes is omitted).

allowedGrantTypesstring[]

Allowed grant types. Defaults to ["authorization_code", "refresh_token"] if omitted (applied by the service, not Zod).

allowedScopesstring[] required

Scopes the app can request (non-empty)

homepageUrlstring uri

App homepage URL (shown during authorization)

privacyPolicyUrlstring uri

Privacy policy URL

termsOfServiceUrlstring uri

Terms of service URL

isConfidentialboolean

Whether the app can securely store secrets.

  • true: Server-side app (secret required for token requests)
  • false: Browser/mobile app (must use PKCE)
accessTokenLifetimeinteger

Access token lifetime in seconds (300–86400)

refreshTokenLifetimeinteger

Refresh token lifetime in seconds (3600–31536000)

Example request

{
  "name": "My Integration App",
  "description": "Integrates PipesHub with our internal tools",
  "redirectUris": [
    "https://myapp.com/callback",
    "http://localhost:3000/callback"
  ],
  "allowedGrantTypes": [
    "authorization_code",
    "refresh_token"
  ],
  "allowedScopes": [
    "openid",
    "profile",
    "read:records"
  ],
  "accessTokenLifetime": 3600,
  "refreshTokenLifetime": 2592000
}

Response

OAuth app created successfully

messagestring required

Example response

{
  "message": "OAuth app created successfully"
}