Truss OAuth Integration Guide

This guide provides step-by-step instructions for developers looking to integrate with Truss using OAuth 2.0 authentication. With Truss OAuth, your users can securely authorize your application to access their Truss data without sharing their credentials.

Prerequisites

Before you begin integration, ensure that:

Your users are already onboarded with Truss - OAuth can only be used by users who have completed Truss onboarding
You have obtained OAuth credentials from Truss - Contact Truss directly to request:
- client_id - Your unique application identifier
- client_secret - Your confidential application secret (keep this secure!)
- Approved redirect_uri - The callback URL where users will be redirected after authorization

⚠️ Important: Keep your client_secret secure and never expose it in client-side code, version control, or logs.

Getting Started

Base URLs

All examples in this guide provide both production and sandbox URLs:

Production: https://app.trusspayments.com
Sandbox: https://app.staging.trusspayments.com

Note: Staging test users and companies must be signed up and onboarded as they would in production.

OAuth Flow Overview

Truss implements the OAuth 2.0 Authorization Code flow, which consists of:

Authorization Request - Redirect the user to Truss for authentication
Authorization Grant - User authorizes your application
Token Exchange - Exchange the authorization code for access and refresh tokens
API Access - Use the access token to make authenticated API requests
Token Refresh - Use the refresh token to obtain new access tokens when they expire

┌─────────────┐                                           ┌─────────────┐
│             │  1. Redirect to Authorization URL         │             │
│  Your App   │──────────────────────────────────────────>│    Truss    │
│             │                                           │             │
│             │  2. User Authorizes & Redirect with Code  │             │
│             │<──────────────────────────────────────────│             │
│             │                                           │             │
│             │  3. Exchange Code for Tokens              │             │
│             │──────────────────────────────────────────>│   Token     │
│             │                                           │  Endpoint   │
│             │  4. Return Access & Refresh Tokens        │             │
│             │<──────────────────────────────────────────│             │
│             │                                           │             │
│             │  5. API Request with Access Token         │             │
│             │──────────────────────────────────────────>│  Truss API  │
└─────────────┘                                           └─────────────┘

Step 1: Initiate OAuth Authorization

To begin the OAuth flow, redirect the user to Truss's authorization endpoint with the required parameters.

Authorization Endpoint

Production:

GET https://app.trusspayments.com/oauth/authorize

Sandbox:

GET https://app.staging.trusspayments.com/oauth/authorize

Required Parameters

Parameter	Description	Example
`client_id`	Your application's client ID	`your-client-id`
`redirect_uri`	Your registered callback URL	`https://yourapp.com/oauth/callback`
`response_type`	Must be `code` for authorization code flow	`code`
`scope`	Space-separated list of requested scopes	`payment_intent.inbound:read payment_intent.inbound:write offline_access`
`state`	Random string for CSRF protection (recommended)	`random-state-string`

Example Authorization URL

Production:

https://app.trusspayments.com/oauth/authorize
  ?client_id=your-client-id
  &redirect_uri=https://yourapp.com/oauth/callback
  &response_type=code
  &scope=payment_intent.inbound:write+offline_access
  &state=random-state-string

Sandbox:

https://app.staging.trusspayments.com/oauth/authorize
  ?client_id=your-client-id
  &redirect_uri=https://yourapp.com/oauth/callback
  &response_type=code
  &scope=payment_intent.inbound:write+offline_access
  &state=random-state-string

Step 2: Handle Authorization Callback

After the user authorizes your application, Truss will redirect them back to your redirect_uri with an authorization code.

Callback Parameters

If successful, your callback URL will receive:

Parameter	Description
`code`	The authorization code (short-lived, single-use)
`state`	The state parameter you provided (validate this matches!)

Step 3: Exchange Authorization Code for Tokens

Once you have the authorization code, exchange it for access and refresh tokens by making a server-side POST request to the token endpoint.

⚠️ Security Note: This step MUST be performed on your backend server, never in client-side code, as it requires your client_secret.

Token Endpoint

Production: https://bold-jester-7561.customers.stytch.com/v1/oauth2/token

Sandbox: https://vine-fire-5666.customers.stytch.dev/v1/oauth2/token

Note: Production token endpoint is planned to be updated to use a trusspayments.com domain.

Make a POST request with Content-Type: application/x-www-form-urlencoded and these parameters:

grant_type=authorization_code
code (the authorization code from callback)
redirect_uri (must match the URI from Step 1)
client_id (your client ID)
client_secret (your client secret)

Response: Returns access_token, refresh_token, token_type, expires_in, and scope.

Documentation: Exchange Authorization Code for Access Token

Using the Access Token

Include the access token in the Authorization header when making API requests to Truss:

Authorization: Bearer {access_token}

⏱️ Token Expiry: Access tokens expire after 60 minutes. Use the refresh token to obtain a new access token before expiry (see Step 4).

Step 4: Refreshing Access Tokens

Access tokens expire after 60 minutes. Use your refresh token to obtain a new access token without requiring the user to re-authorize.

Token Refresh Endpoint

Production: https://bold-jester-7561.customers.stytch.com/v1/oauth2/token

Sandbox: https://vine-fire-5666.customers.stytch.dev/v1/oauth2/token

Note: Production token endpoint is planned to be updated to use a trusspayments.com domain.

Make a POST request with Content-Type: application/x-www-form-urlencoded and these parameters:

grant_type=refresh_token
refresh_token (your current refresh token)
client_id (your client ID)
client_secret (your client secret)

Response: Returns a new access_token and potentially a new refresh_token (depending on your client type and token rotation settings).

⚠️ Important: Always check for a new refresh_token in the response and update your stored token accordingly.

⏱️ Refresh Token Expiry: The refresh token has an initial expiry of 6 months, and each use extends its lifetime by another 3 months.

Documentation: Exchange Refresh Token for Access Token

Scopes

For detailed information about available OAuth scopes and their permissions, see the Scopes documentation.

Testing Your Integration

Use Staging Environment

Test your integration in the staging environment before going to production.

Last Updated: January 2026

Version: 1.0