Authentication

OAuth 2.0 client credentials

All authenticated API endpoints use the OAuth 2.0 client credentials grant. You exchange a clientId and clientSecret for a short-lived JWT access token, then send that token (plus your x-client-id) on every subsequent request.

Note

Your credentials are issued during onboarding and have a strict format:

• clientId matches ^org_[a-f0-9]{32}$ — e.g. org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
• clientSecret matches ^[a-f0-9]{32}_[a-f0-9]{32}$

Treat the clientSecret like a password. Never expose it in a browser, mobile app, or public repository.

Auth flow diagram

The following diagram illustrates the authentication flow with Pipevest.

Usage

Exchange credentials for a token

Send a JSON body to POST /v1/oauth/token. A successful exchange returns HTTP 200.

  curl --request POST \
    --url https://api.staging.pipevest.com/v1/oauth/token \
    --header 'Content-Type: application/json' \
    --data '{
      "clientId": "org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "clientSecret": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
    }'

The response contains the bearer token and its metadata:

{
  "message": "Authentication successful",
  "tokenId": "b0f6e2a1-9c3d-4e5f-8a7b-6c5d4e3f2a1b",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "maxTTL": 86400,
  "tokenType": "Bearer",
  "scope": ["READ", "WRITE"],
  "trustedIps": [],
  "organization": {
    "id": "clx0a1b2c3d4e5f6g7h8i9j0k",
    "name": "Acme Investments",
    "clientId": "org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
  },
  "createdAt": 1752566400,
  "updatedAt": 1752566400
}

Tip

Tokens are short-lived: expiresIn is 3600 seconds (1 hour). Re-authenticate before expiry rather than on every request.

Call authenticated endpoints

Send the token as a Bearer token in the Authorization header, and repeat your clientId in the x-client-id header. The x-client-id must match the clientId embedded in the token, or the request is rejected with 401.

  curl --request GET \
    --url https://api.staging.pipevest.com/v1/customers \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d'

Revoke the token when you are done (optional)

To invalidate a token before it expires (e.g. on logout), call POST /v1/oauth/revoke with the token you want to revoke. It is a header-based call — no request body or query parameters. A success returns HTTP 200 and the token is blacklisted for all future requests.

  curl --request POST \
    --url https://api.staging.pipevest.com/v1/oauth/revoke \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d'

Caution

The curl examples above show only the authentication headers. Every call that carries Authorization + x-client-id — including GET /v1/oauth/me and POST /v1/oauth/revoke — must also be signed, or it is rejected with 401 Signature verification failed. Add the Signature, Signature-Input and (for requests with a body) Content-Digest headers described in Message Signature.

The only unsigned call is POST /v1/oauth/token, the token exchange itself.

Note

Examples use the Sandbox (UAT) host https://api.staging.pipevest.com. Production is https://api.pipevest.com. Both are Pipevest-hosted; your contact confirms access during onboarding.

Inspect the authenticated organization

Call GET /v1/oauth/me with a valid token to retrieve the profile of the authenticated organization (and its active credentials). See the Authentication guide for the full request and response.

Scopes

Note

Granular scopes are not yet enforced. Every token is issued with both READ and WRITE scope.

Name	Permission	Status
READ	Read access across all resources	ACTIVE
WRITE	Write access across all resources	ACTIVE

HTTP Signatures

Learn how signed requests protect API integrity