Authentication

Overview

The Finale GraphQL API uses HTTP Basic Authentication with API credentials (an API key and secret). This page covers authentication setup, working examples in multiple languages, and troubleshooting.

API Endpoint

POST https://app.finaleinventory.com/{accountPathComponent}/api/graphql

Replace {accountPathComponent} with your Finale account identifier. You can find your accountPathComponent in your Finale URL when logged in: https://app.finaleinventory.com/YOUR-ACCOUNT-PATH.

Generating API Credentials

Before authenticating, you need to generate API credentials from your Finale account.

See How to Generate API Keys for step-by-step instructions on creating and managing your API credentials.

API Key Permissions

All API keys in Finale have full access to your account:

• Full Access: Every API key has complete access to all data and operations within the account
• No Permission Scopes: There are no different permission levels or restricted scopes for API keys
• Key Revocation: Keys can be revoked immediately through Application Settings > Users > API keys
• Key Rotation: Generate new keys and revoke old ones to rotate credentials safely

Authentication Method

Use HTTP Basic Authentication with your API key as the username and API secret as the password. All standard HTTP client libraries support Basic Authentication automatically.

Usage Limits

Finale has API usage limits to ensure system stability. For details about usage policies and limits, see the Rate limits documentation.

Examples

JavaScript (Node.js)

const apiKey = 'your-api-key';
const apiSecret = 'your-api-secret';
const accountPathComponent = 'your-account';

const credentials = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

const query = `
  query {
    productViewConnection(first: 5) {
      edges {
        node {
          productId
        }
      }
    }
  }
`;

fetch(`https://app.finaleinventory.com/${accountPathComponent}/api/graphql`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${credentials}`
  },
  body: JSON.stringify({ query })
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Python

import requests
import base64

api_key = 'your-api-key'
api_secret = 'your-api-secret'
account_path_component = 'your-account'

credentials = base64.b64encode(f'{api_key}:{api_secret}'.encode()).decode()

query = """
query {
  productViewConnection(first: 5) {
    edges {
      node {
        productId
      }
    }
  }
}
"""

url = f'https://app.finaleinventory.com/{account_path_component}/api/graphql'
headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Basic {credentials}'
}
payload = {'query': query}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

cURL

curl -X POST "https://app.finaleinventory.com/your-account/api/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'your-api-key:your-api-secret' | base64)" \
  -d '{
    "query": "query { productViewConnection(first: 5) { edges { node { productId } } } }"
  }'

Common Authentication Errors

401 Unauthorized

Cause: Invalid API credentials or incorrect format

Response Example:

{
  "errors": [
    {
      "message": "Authentication failed",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Troubleshooting:

• Verify your API key and secret are correct
• Check that you're using key:secret format (not secret:key)
• Ensure credentials are properly Base64 encoded
• Confirm the key hasn't been revoked

404 Not Found

Cause: Incorrect accountPathComponent in URL

Troubleshooting:

• Verify your accountPathComponent matches your Finale URL
• Check for typos in the endpoint URL
• Ensure you're using the correct API endpoint format

Security Requirements

• HTTPS Required: All API requests must use HTTPS
• Credential Storage: Store API credentials securely using environment variables or secure credential management systems
• Key Revocation: If a key is compromised, revoke it immediately through Application Settings > Users > API keys
• Monitor Usage: Review API key usage regularly through your account audit logs