Skip to content
Pipevest Developers

Authentication

OAuth 2.0 client-credentials access tokens authenticate every call to the Pipevest API. This guide shows how to create a token, inspect the authenticated organization, and revoke a token.

Create an access token

Section titled “Create an access token”

Send your clientId and clientSecret as a JSON body to POST /v1/oauth/token. A successful exchange returns HTTP 200.

Terminal window
  curl --request POST \
    --url https://api.staging.pipevest.com/v1/oauth/token \
    --header 'Content-Type: application/json' \
    --data '{
      "clientId": "org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "clientSecret": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
    }'
{
  "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
}

Invalid or inactive credentials return HTTP 401:

{
  "error": "Unauthorized",
  "message": "Invalid client credentials"
}

Authenticate your requests

Section titled “Authenticate your requests”

Send the token as a Bearer token and repeat your clientId in the x-client-id header. The x-client-id value must match the clientId inside the token or the request is rejected with 401 "Client ID mismatch".

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

Inspect the authenticated organization

Section titled “Inspect the authenticated organization”

GET /v1/oauth/me returns the profile of the organization the token belongs to, including its active credentials. Returns HTTP 200.

Terminal window
  curl --request GET \
    --url https://api.staging.pipevest.com/v1/oauth/me \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d'
{
  "data": {
    "id": "clx0a1b2c3d4e5f6g7h8i9j0k",
    "name": "Acme Investments",
    "description": "Retail investment partner",
    "website": "https://acme.example",
    "email": "engineering@acme.example",
    "phone": "260971234567",
    "address": "Lusaka, Zambia",
    "isActive": true,
    "createdAt": "2026-01-05T09:12:00.000Z",
    "updatedAt": "2026-07-10T14:30:00.000Z",
    "credentials": [
      {
        "id": "clcreda1b2c3d4e5f6g7h8i9j0",
        "name": "Production key",
        "clientId": "org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
        "expiresAt": null,
        "lastUsedAt": "2026-07-15T08:00:00.000Z",
        "createdAt": "2026-01-05T09:12:00.000Z"
      }
    ]
  }
}

Revoke an access token

Section titled “Revoke an access token”

To invalidate a token before it expires (e.g. on logout), call POST /v1/oauth/revoke. This is a header-based call — there is no request body and no query parameters. The token in the Authorization header is blacklisted and rejected on all future requests. Returns HTTP 200.

Terminal window
  curl --request POST \
    --url https://api.staging.pipevest.com/v1/oauth/revoke \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: org_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d'
{
  "message": "Token revoked successfully"
}

Token response reference

Section titled “Token response reference”
Property Definition
message Authentication response message
tokenId Unique access token identifier (JWT jti)
token Short-lived bearer access token. TTL of 3600s
expiresIn Token’s current TTL, in seconds (3600)
maxTTL Token’s maximum lifetime, in seconds (86400)
tokenType Authorization type — always Bearer
scope Authorization scopes — currently ["READ", "WRITE"]
trustedIps IP addresses allowlisted for this credential
organization Object containing id, name and clientId
createdAt Created-at Unix timestamp
updatedAt Updated-at Unix timestamp
Authentication Concepts

Review the auth mechanisms that keep the API secure