Authentication

Learn how to authenticate with the Receiptrail API using Personal Access Tokens (PAT) from Logto.

Overview

The Receiptrail API uses OAuth 2.0 token exchange for authentication. You can use a Personal Access Token (PAT) to obtain an access token that grants programmatic access to the API without requiring interactive login.

This is ideal for CI/CD pipelines, automation scripts, server-to-server integrations, and backend applications that need to access the API on behalf of a user.

Step 1: Create a Personal Access Token

First, create a Personal Access Token (PAT) from your account:

Sign in to the Receiptrail Dashboard
Navigate to your Profile Settings
Go to the "Personal Access Tokens" section
Click "Create Token"
Provide a descriptive name for your token (e.g., "CI/CD Pipeline", "Backend Service")
Set an expiration date (optional but recommended for security)
Copy the generated token immediately - it will only be shown once

Security Warning

Keep your PAT secure and never commit it to version control. Store it in environment variables or a secure secret manager.

Step 2: Exchange PAT for Access Token

Use the OAuth 2.0 Token Exchange grant to convert your PAT into an access token that can be used to authenticate API requests.

Request Parameters

Parameter	Required	Description
client_id	Yes	`bzkla5f5dhx5bkpm06izv`
grant_type	Yes	`urn:ietf:params:oauth:grant-type:token-exchange`
subject_token	Yes	Your Personal Access Token
subject_token_type	Yes	`urn:logto:token-type:personal_access_token`
resource	Optional	API resource indicator (e.g., `https://api.receiptrail.ai`)
scope	Optional	Requested scopes (space-separated)

cURL Example

curl -X POST https://identity.receiptrail.ai/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=bzkla5f5dhx5bkpm06izv" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=YOUR_PERSONAL_ACCESS_TOKEN" \
  -d "subject_token_type=urn:logto:token-type:personal_access_token" \
  -d "resource=https://api.receiptrail.ai"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "scope": "openid"
}

access_token - The JWT access token to use in API requests

token_type - Always "Bearer"

expires_in - Token lifetime in seconds (typically 3600 = 1 hour)

Step 3: Use the Access Token

Include the access token in the Authorization header of your API requests:

Authorization: Bearer <access_token>

Code Examples

Node.js

const axios = require('axios');

async function getAccessToken(personalAccessToken) {
  const response = await axios.post(
    'https://identity.receiptrail.ai/oidc/token',
    new URLSearchParams({
      client_id: 'bzkla5f5dhx5bkpm06izv',
      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
      subject_token: personalAccessToken,
      subject_token_type: 'urn:logto:token-type:personal_access_token',
      resource: 'https://api.receiptrail.ai',
    }),
    {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
    }
  );

  return response.data.access_token;
}

// Usage
const accessToken = await getAccessToken('pat_xxxxx');

// Use the token in API requests
const apiResponse = await axios.get('https://api.receiptrail.ai/receipts', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

Python

import requests

def get_access_token(personal_access_token: str) -> str:
    response = requests.post(
        'https://identity.receiptrail.ai/oidc/token',
        data={
            'client_id': 'bzkla5f5dhx5bkpm06izv',
            'grant_type': 'urn:ietf:params:oauth:grant-type:token-exchange',
            'subject_token': personal_access_token,
            'subject_token_type': 'urn:logto:token-type:personal_access_token',
            'resource': 'https://api.receiptrail.ai',
        },
        headers={
            'Content-Type': 'application/x-www-form-urlencoded',
        }
    )
    response.raise_for_status()
    return response.json()['access_token']

# Usage
access_token = get_access_token('pat_xxxxx')

# Use the token in API requests
api_response = requests.get(
    'https://api.receiptrail.ai/receipts',
    headers={'Authorization': f'Bearer {access_token}'}
)

Token Management Best Practices

Cache access tokens - Reuse tokens until they expire to minimize token exchange requests
Refresh proactively - Request a new token before the current one expires (e.g., at 80% of lifetime)
Rotate PATs regularly - Create new PATs periodically and revoke old ones
Use environment variables - Never hardcode tokens in your source code
Use the SDK - The official SDKs handle token exchange and caching automatically

Next Steps

Use the Official SDK

The easiest way to handle authentication is to use the official Receiptrail SDK, which manages token exchange and caching automatically.

View SDK Setup Guide

Explore API Endpoints

Browse all available endpoints and learn how to integrate receipt processing into your application.

View All Endpoints