> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.filed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer integration guide

> Learn how to integrate Filed's API as a customer and authenticate your requests

<Warning>
  **Are you a partner?** If you are an official Filed partner managing multiple tax firm customers, please use the [Partner integration guide](/legacy/apis/guides/partner) instead.
</Warning>

This guide walks you through the complete API integration process for customers, from generating your API key to making your first authenticated request. Follow these steps to start building with Filed's API.

## Prerequisites

Before you begin, ensure you have:

* An active Filed account
* Access to Developer Settings in your workspace
* GraphQL endpoint: `https://gateway.filed.com/graphql`

<Info>
  If you need assistance accessing Developer Settings or have questions about API access, please contact [support@filed.com](mailto:support@filed.com)
</Info>

## Overview

The API integration process consists of three simple steps:

1. **Generate API Key** from Developer Settings
2. **Exchange API Key** for an access token
3. **Make authenticated requests** to the Filed API

***

## Step 1: Generate API Key

Navigate to Developer Settings in your Filed workspace to generate your API key.

<Steps>
  <Step title="Access Developer Settings">
    Log in to your Filed account and navigate to **Settings** → **Developer Settings**
  </Step>

  <Step title="Generate New API Key">
    Click **Generate API Key** and provide a descriptive name for your key (e.g., "Production Integration", "Development Testing")
  </Step>

  <Step title="Save Your API Key">
    Copy and securely store your API key immediately - you won't be able to see it again
  </Step>
</Steps>

<Warning>
  **Security Best Practice**: Store your API key securely and never commit it to version control. Use environment variables or secure secret management tools.
</Warning>

***

## Step 2: Exchange API Key for Access Token

Use your API key to obtain an access token that will authenticate all your API requests.

#### GraphQL Mutation

<CodeGroup>
  ```graphql GraphQL theme={null}
  mutation LoginViaPersonalApiToken($apiKey: String!) {
    loginViaPersonalApiToken(token: $apiKey) {
      accessToken
    }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://gateway.filed.com/graphql \
    -H "Content-Type: application/json" \
    -H "source-platform: tax-firm-a" \
    -d '{
      "query": "mutation LoginViaPersonalApiToken($apiKey: String!) { loginViaPersonalApiToken(token: $apiKey) { accessToken } }",
      "variables": {
        "apiKey": "your-api-key-here"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://gateway.filed.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'source-platform': 'tax-firm-a'
    },
    body: JSON.stringify({
      query: `
        mutation LoginViaPersonalApiToken($apiKey: String!) {
          loginViaPersonalApiToken(token: $apiKey) {
            accessToken
          }
        }
      `,
      variables: {
        apiKey: 'your-api-key-here'
      }
    })
  });

  const { data } = await response.json();
  const accessToken = data.loginViaPersonalApiToken.accessToken;
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://gateway.filed.com/graphql',
      headers={
          'source-platform': 'tax-firm-a'
      },
      json={
          'query': '''
            mutation LoginViaPersonalApiToken($apiKey: String!) {
              loginViaPersonalApiToken(token: $apiKey) {
                accessToken
              }
            }
          ''',
          'variables': {
              'apiKey': 'your-api-key-here'
          }
      }
  )

  data = response.json()
  access_token = data['data']['loginViaPersonalApiToken']['accessToken']
  ```

  ```json Response theme={null}
  {
    "data": {
      "loginViaPersonalApiToken": {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
  ```
</CodeGroup>

#### Implementation Notes

* Store the `accessToken` securely and use it in the `Authorization` header for all subsequent requests
* Access tokens are valid for a limited time; implement token refresh logic as needed
* Format: `Authorization: Bearer <accessToken>`
* Include a `source-platform` header with a custom identifier for your integration (e.g., `tax-firm-a`, `my-sample-platform`, `qount`). This header is used to uniquely identify API requests for analytical purposes and does not affect rate limits or any other API functionality.

***

## Step 3: Verify Your Connection

Make a test request to verify your API key works correctly. The `me` query returns information about the authenticated user.

#### GraphQL Query

<CodeGroup>
  ```graphql GraphQL theme={null}
  query Me {
    me {
      id
      name
    }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://gateway.filed.com/graphql \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your-access-token-here" \
    -H "source-platform: tax-firm-a" \
    -d '{
      "query": "query Me { me { id name } }"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://gateway.filed.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'source-platform': 'tax-firm-a'
    },
    body: JSON.stringify({
      query: `
        query Me {
          me {
            id
            name
          }
        }
      `
    })
  });

  const { data } = await response.json();
  console.log('Current user:', data.me);
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://gateway.filed.com/graphql',
      headers={
          'Authorization': f'Bearer {access_token}',
          'source-platform': 'tax-firm-a'
      },
      json={
          'query': '''
            query Me {
              me {
                id
                name
              }
            }
          '''
      }
  )

  data = response.json()
  user = data['data']['me']
  print(f"Current user ID: {user['id']}")
  ```

  ```json Response theme={null}
  {
    "data": {
      "me": {
        "id": "user_123456",
        "name": "John Doe"
      }
    }
  }
  ```
</CodeGroup>

#### Implementation Notes

* The `me` query returns information about the currently authenticated user
* A successful response confirms your API integration is working correctly
* The `id` field uniquely identifies the authenticated user

<Info>
  **Success!** If you receive a valid response with your user information, your API integration is working correctly and you're ready to start building.
</Info>

***

## Complete Integration Example

Here's a complete example showing all three steps together:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const GRAPHQL_ENDPOINT = 'https://gateway.filed.com/graphql';
  const API_KEY = process.env.FILED_API_KEY;

  async function integrateWithFiled() {
    // Step 2: Exchange API Key for Access Token
    const authResponse = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'source-platform': 'tax-firm-a'
      },
      body: JSON.stringify({
        query: `
          mutation LoginViaPersonalApiToken($apiKey: String!) {
            loginViaPersonalApiToken(token: $apiKey) {
              accessToken
            }
          }
        `,
        variables: { apiKey: API_KEY }
      })
    });

    const { data: authData } = await authResponse.json();
    const accessToken = authData.loginViaPersonalApiToken.accessToken;
    
    console.log('✓ Successfully authenticated');

    // Step 3: Verify Connection
    const meResponse = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`,
        'source-platform': 'tax-firm-a'
      },
      body: JSON.stringify({
        query: `
          query Me {
            me {
              id
              name
            }
          }
        `
      })
    });

    const { data: meData } = await meResponse.json();
    console.log('✓ Connection verified');
    console.log('Current user:', meData.me);
    
    return { accessToken, user: meData.me };
  }

  // Run the integration
  integrateWithFiled()
    .then(({ user }) => {
      console.log(`\n🎉 Integration successful! User ID: ${user.id}`);
    })
    .catch(error => {
      console.error('Integration failed:', error);
    });
  ```

  ```typescript TypeScript theme={null}
  const GRAPHQL_ENDPOINT = 'https://gateway.filed.com/graphql';
  const API_KEY = process.env.FILED_API_KEY!;

  interface AuthResponse {
    data: {
      loginViaPersonalApiToken: {
        accessToken: string;
      };
    };
  }

  interface MeResponse {
    data: {
      me: {
        id: string;
        name: string | null;
      };
    };
  }

  async function integrateWithFiled() {
    // Step 2: Exchange API Key for Access Token
    const authResponse = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'source-platform': 'tax-firm-a'
      },
      body: JSON.stringify({
        query: `
          mutation LoginViaPersonalApiToken($apiKey: String!) {
            loginViaPersonalApiToken(token: $apiKey) {
              accessToken
            }
          }
        `,
        variables: { apiKey: API_KEY }
      })
    });

    const { data: authData } = await authResponse.json() as AuthResponse;
    const accessToken = authData.loginViaPersonalApiToken.accessToken;
    
    console.log('✓ Successfully authenticated');

    // Step 3: Verify Connection
    const meResponse = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`,
        'source-platform': 'tax-firm-a'
      },
      body: JSON.stringify({
        query: `
          query Me {
            me {
              id
              name
            }
          }
        `
      })
    });

    const { data: meData } = await meResponse.json() as MeResponse;
    console.log('✓ Connection verified');
    console.log('Current user:', meData.me);
    
    return { accessToken, user: meData.me };
  }

  // Run the integration
  integrateWithFiled()
    .then(({ user }) => {
      console.log(`\n🎉 Integration successful! User ID: ${user.id}`);
    })
    .catch(error => {
      console.error('Integration failed:', error);
    });
  ```

  ```python Python theme={null}
  import os
  import requests
  from typing import Dict, Any

  GRAPHQL_ENDPOINT = 'https://gateway.filed.com/graphql'
  API_KEY = os.environ.get('FILED_API_KEY')

  def integrate_with_filed() -> Dict[str, Any]:
      # Step 2: Exchange API Key for Access Token
      auth_query = """
        mutation LoginViaPersonalApiToken($apiKey: String!) {
          loginViaPersonalApiToken(token: $apiKey) {
            accessToken
          }
        }
      """
      
      auth_response = requests.post(
          GRAPHQL_ENDPOINT,
          headers={
              'source-platform': 'tax-firm-a'
          },
          json={
              'query': auth_query,
              'variables': {'apiKey': API_KEY}
          }
      )
      
      auth_data = auth_response.json()
      access_token = auth_data['data']['loginViaPersonalApiToken']['accessToken']
      print('✓ Successfully authenticated')
      
      # Step 3: Verify Connection
      me_query = """
        query Me {
          me {
            id
            name
          }
        }
      """
      
      me_response = requests.post(
          GRAPHQL_ENDPOINT,
          headers={
              'Authorization': f'Bearer {access_token}',
              'source-platform': 'tax-firm-a'
          },
          json={'query': me_query}
      )
      
      me_data = me_response.json()
      user = me_data['data']['me']
      print('✓ Connection verified')
      print(f'Current user: {user}')
      
      return {
          'access_token': access_token,
          'user': user
      }

  if __name__ == '__main__':
      try:
          result = integrate_with_filed()
          print(f"\n🎉 Integration successful! User ID: {result['user']['id']}")
      except Exception as e:
          print(f'Integration failed: {e}')
  ```
</CodeGroup>

***

## Best Practices

### Security

1. **Never expose API keys**: Store API keys in environment variables or secure secret management systems
2. **Use HTTPS**: Always make API requests over HTTPS
3. **Validate inputs**: Always validate user inputs before making API calls

### Error handling

1. **Handle authentication errors**: Implement retry logic for expired tokens
2. **Validate responses**: Check for errors in GraphQL responses
3. **Log errors**: Maintain error logs for debugging and monitoring

***

## Next Steps

Now that you've successfully integrated with Filed's API, you can:

1. **Explore the API**: Browse the full [API reference](/legacy/apis/introduction) to discover available queries and mutations
2. **Build features**: Start implementing features using Filed's GraphQL API
3. **Monitor usage**: Track your API usage and monitor for errors

***

## Support

Need help with your integration?

* **Email**: [support@filed.com](mailto:support@filed.com)
* **Documentation**: Browse our [API documentation](/legacy/apis/introduction) for more details

We're here to help you succeed with Filed's API!