OAuth 2.0 Setup Guide - GetBill Integrations

Overview

This guide walks you through setting up OAuth 2.0 authentication for the GetBill API. OAuth 2.0 provides secure, standardized authorization that allows your application to access GetBill data on behalf of your company.

Why OAuth 2.0?

Security

Your credentials are never stored in the client application. Tokens can be revoked without changing passwords.

Scoped Access

Request only the permissions your application needs. Users can see exactly what access they’re granting.

Standardized

OAuth 2.0 is an industry standard supported by all major platforms and programming languages.

Scalable

Suitable for everything from simple scripts to large enterprise integrations.

Step 1: Create an OAuth Client

Access Your Dashboard

Log in to your GetBill account
Navigate to Company
Find the API Client Management section
Click Create New OAuth Client

Configure Your Client

API clients use Client Credentials automatically for server-to-server authentication. There is no authentication flow to select.

Save Your Credentials

After creating the client, you’ll receive:

string

Public identifier for your application (safe to store in client-side code)

string

Secret key for your application (keep this secure!)

Store your Client Secret securely! Never commit it to version control or expose it in client-side code.

Step 2: Request an Access Token

Client Credentials Flow

Best for: Server-to-server applications, background jobs, automated systems When to use:

Your application runs on a secure server
No user interaction is required
You’re accessing your own company’s data

Flow:

Your application requests a token directly from the authorization server
No user authorization step is required
Token is returned immediately

Step 3: Implementation Examples

Client Credentials Implementation

JavaScript (Node.js)
Python
PHP

class GetBillOAuthClient {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.accessToken = null;
    this.expiresAt = null;
  }

  async getAccessToken() {
    if (this.accessToken && this.expiresAt > Date.now()) {
      return this.accessToken;
    }

    return this.requestNewToken();
  }

  async requestNewToken() {
    const response = await fetch('https://getbill.io/oauth/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: 'debts:read debts:write followups:read company:read'
      })
    });

    if (!response.ok) {
      throw new Error(`Token request failed: ${response.statusText}`);
    }

    const tokenData = await response.json();
    this.updateToken(tokenData);
    return this.accessToken;
  }

  updateToken(tokenData) {
    this.accessToken = tokenData.access_token;
    this.expiresAt = Date.now() + (tokenData.expires_in * 1000) - 60000; // 1 min buffer
  }

  async makeAPIRequest(endpoint, options = {}) {
    const token = await this.getAccessToken();
    
    return fetch(`https://getbill.io/external-api/v1${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
  }
}

// Usage
const client = new GetBillOAuthClient('your_client_id', 'your_client_secret');

// Make API calls
const response = await client.makeAPIRequest('/company/profile');
const profile = await response.json();

import requests
from datetime import datetime, timedelta

class GetBillOAuthClient:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self.access_token = None
        self.expires_at = None

    def get_access_token(self):
        if self.access_token and self.expires_at > datetime.now():
            return self.access_token

        return self.request_new_token()

    def request_new_token(self):
        data = {
            'grant_type': 'client_credentials',
            'client_id': self.client_id,
            'client_secret': self.client_secret,
            'scope': 'debts:read debts:write followups:read company:read'
        }

        response = requests.post(
            'https://getbill.io/oauth/token',
            data=data
        )
        response.raise_for_status()

        token_data = response.json()
        self.update_token(token_data)
        return self.access_token

    def update_token(self, token_data):
        self.access_token = token_data['access_token']
        expires_in = token_data.get('expires_in', 3600)
        self.expires_at = datetime.now() + timedelta(seconds=expires_in - 60)

    def make_api_request(self, endpoint, method='GET', **kwargs):
        token = self.get_access_token()
        
        headers = kwargs.get('headers', {})
        headers['Authorization'] = f'Bearer {token}'
        headers['Content-Type'] = 'application/json'
        kwargs['headers'] = headers

        return requests.request(
            method,
            f'https://getbill.io/external-api/v1{endpoint}',
            **kwargs
        )

# Usage
client = GetBillOAuthClient('your_client_id', 'your_client_secret')

# Make API calls
response = client.make_api_request('/company/profile')
profile = response.json()

<?php

class GetBillOAuthClient {
    private $clientId;
    private $clientSecret;
    private $accessToken;
    private $expiresAt;

    public function __construct($clientId, $clientSecret) {
        $this->clientId = $clientId;
        $this->clientSecret = $clientSecret;
    }

    public function getAccessToken() {
        if ($this->accessToken && $this->expiresAt > time()) {
            return $this->accessToken;
        }

        return $this->requestNewToken();
    }

    private function requestNewToken() {
        $data = [
            'grant_type' => 'client_credentials',
            'client_id' => $this->clientId,
            'client_secret' => $this->clientSecret,
            'scope' => 'debts:read debts:write followups:read company:read'
        ];

        $response = $this->makeHttpRequest('https://getbill.io/oauth/token', $data);
        $this->updateToken($response);
        return $this->accessToken;
    }

    private function updateToken($tokenData) {
        $this->accessToken = $tokenData['access_token'];
        $expiresIn = $tokenData['expires_in'] ?? 3600;
        $this->expiresAt = time() + $expiresIn - 60; // 1 min buffer
    }

    public function makeAPIRequest($endpoint, $method = 'GET', $data = null) {
        $token = $this->getAccessToken();
        
        $headers = [
            'Authorization: Bearer ' . $token,
            'Content-Type: application/json'
        ];

        $url = 'https://getbill.io/external-api/v1' . $endpoint;
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        
        if ($data) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new Exception("API request failed with status $httpCode");
        }

        return json_decode($response, true);
    }

    private function makeHttpRequest($url, $data) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new Exception("Token request failed with status $httpCode");
        }

        return json_decode($response, true);
    }
}

// Usage
$client = new GetBillOAuthClient('your_client_id', 'your_client_secret');

// Make API calls
$profile = $client->makeAPIRequest('/company/profile');
?>

Step 4: Security Best Practices

Secure Token Storage

Use environment variables for client secrets
Store tokens securely (encrypted database, secure session storage)
Never log or expose tokens in error messages

Minimal Scopes

Request only the scopes your integration needs
Review granted scopes regularly
Remove permissions that are no longer required

HTTPS Only

Always use HTTPS for all OAuth flows
Validate SSL certificates
Never send tokens over unencrypted connections

Token Management

Request a new token before expiration
Handle token expiration gracefully
Revoke tokens when no longer needed

Environment Variables Example

# .env file
GETBILL_CLIENT_ID=your_client_id_here
GETBILL_CLIENT_SECRET=your_client_secret_here

// Load from environment
const CLIENT_ID = process.env.GETBILL_CLIENT_ID;
const CLIENT_SECRET = process.env.GETBILL_CLIENT_SECRET;

Step 5: Testing Your Setup

Test Client Credentials

curl -X POST https://getbill.io/oauth/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" \
  -d "scope=company:read"

Troubleshooting

invalid_client Error

Cause: Incorrect client ID or secretSolution:

Double-check your client credentials
Ensure you’re using the correct environment (test vs production)
Verify the client is active in your dashboard

invalid_scope Error

Cause: Requesting scopes not granted to your clientSolution:

Check your client configuration in the dashboard
Request only the scopes you need
Contact support if you need additional scopes

unsupported_grant_type Error

Cause: Invalid or unsupported grant typeSolution:

Send grant_type=client_credentials
Use the /oauth/token endpoint
Check that the request body uses form encoding

Production Considerations

Scaling OAuth

Token Caching: Cache tokens in Redis or similar for multiple server instances
Secure Storage: Store client credentials in a secrets manager
Rate Limiting: Avoid unnecessary token requests by reusing valid access tokens
Monitoring: Monitor token issuance and API authentication failures

Security Hardening

Certificate Pinning: Pin SSL certificates for additional security
Token Rotation: Regularly rotate client secrets
Audit Logging: Log all OAuth events for security monitoring
Scope Minimization: Use the minimum required scopes

Next Steps

Once OAuth is set up:

Make your first API call
Explore the API Reference documentation
Set up webhooks for real-time updates
Review best practices for production use

Need help? Contact our support team at contact@getbill.io

​Overview

​Why OAuth 2.0?

Security

Scoped Access

Standardized

Scalable

​Step 1: Create an OAuth Client

​Access Your Dashboard

​Configure Your Client

​Save Your Credentials

​Step 2: Request an Access Token

​Client Credentials Flow

​Step 3: Implementation Examples

​Client Credentials Implementation

​Step 4: Security Best Practices

Secure Token Storage

Minimal Scopes

HTTPS Only

Token Management

​Environment Variables Example

​Step 5: Testing Your Setup

​Test Client Credentials

​Troubleshooting

​Production Considerations

​Scaling OAuth

​Security Hardening

​Next Steps

Overview

Why OAuth 2.0?

Step 1: Create an OAuth Client

Access Your Dashboard

Configure Your Client

Save Your Credentials

Step 2: Request an Access Token

Client Credentials Flow

Step 3: Implementation Examples

Client Credentials Implementation

Step 4: Security Best Practices

Environment Variables Example

Step 5: Testing Your Setup

Test Client Credentials

Troubleshooting

Production Considerations

Scaling OAuth

Security Hardening

Next Steps