Authentication for Partners

The Partner API uses OAuth 2.0 to authenticate requests. This allows partners to access the API on behalf of their customers.

OAuth 2.0 Client Credentials Flow

Use this flow for server-to-server integrations without user interaction.

When to use: Backend services, automated reporting, batch processing.

Token Endpoints

Environment	URL
Production	https://auth.tidely.com/oauth2/token
Staging	https://auth.sam.tidely.com/oauth2/token

Request

curl -X POST https://auth.tidely.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

Include the access token in the Authorization header of every API request:

curl -X GET https://api.tidely.com/partner/v2/bank-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Account-Id: 12345"

Scopes

Scope	Description
api:read	Read access to all API resources
api:write	Write access to all API resources

Token Expiry

Access tokens expire after 1 hour. After this time a new access token must be requested. Tokens cannot be refreshed — request a new token using your client credentials.

Security Best Practices

• Never expose your client secret in client-side code, version control, or logs
• Store tokens securely using encrypted storage
• Request new tokens proactively before the current token expires to avoid request failures
• Use one set of credentials per integration to simplify credential rotation and access revocation

Tenant Context (Multi-Tenancy)

As a partner, you act on behalf of multiple customer accounts. To specify which customer account a request targets, include the X-Account-Id header in every API request.

How It Works

1. Authenticate using your OAuth 2.0 credentials to obtain an access token
2. Include the X-Account-Id header with the target customer's account ID in each request
3. The API executes the operation in the context of that customer account

A single access token works across all accounts your partner credentials are authorized to access — you can switch between customer accounts without re-authenticating.

Header Details

Header	Type	Required	Description
X-Account-Id	integer	Yes	The unique identifier of the customer account to operate on

Tenant Context Errors

Scenario	HTTP Status	Description
Header missing	400	The X-Account-Id header is required for all partner API requests
Invalid account ID	404	The specified account does not exist
No access to account	403	Your partner credentials are not authorized to access this account

Example: Working with Multiple Customers

# List bank accounts for customer 12345
curl -X GET https://api.tidely.com/partner/v2/bank-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Account-Id: 12345"

# Create a plan for customer 67890 — same token, different account
curl -X POST https://api.tidely.com/partner/v2/plans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Account-Id: 67890" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryName": "E-Commerce Revenue",
    "amount": 50000.00,
    "period": "MONTHLY",
    "date": "2025-01-01",
    "type": "ONE_TIME",
    "name": "January Revenue Target"
  }'