Skip to content

getting-started.md

Latest commit

 

History

History
72 lines (49 loc) · 2.57 KB

getting-started.md

File metadata and controls

72 lines (49 loc) · 2.57 KB
Raw
title Getting started
parent Tutorial
nav_order 1

Getting started

This tutorial walks through installing the SDK, obtaining an access token, and making your first API call.

Prerequisites

Install the package

dotnet add package FreeAgent.Client

The package is currently in alpha prerelease. Pin an exact version if stability matters. See Upgrading and Prerelease and OAuth scope.

OAuth protocol helpers

The SDK provides protocol-level OAuth utilities (FreeAgentOAuthClient): authorisation URL construction, code exchange, and token refresh. It does not host callback endpoints or orchestrate browser flows - your application owns that.

Both FreeAgentOAuthClient and FreeAgentClient default to production. Pass FreeAgentEnvironment.Sandbox on both when you are using a sandbox application - otherwise authorisation and API calls go to production.

using FreeAgent.Client;

var environment = FreeAgentEnvironment.Sandbox; // or FreeAgentEnvironment.Production

var oauthClient = new FreeAgentOAuthClient(
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    redirectUri: "https://localhost:5001/callback",
    environment);

// Redirect the user to FreeAgent
var authUrl = oauthClient.GetAuthorizationUrl(state: "optional-csrf-state");

// In your callback handler, exchange the code for tokens
var token = await oauthClient.ExchangeCodeForTokenAsync(authorizationCode);

Create a client and call the API

using var client = new FreeAgentClient(token.AccessToken, environment);

var company = await client.Company.GetCompanyAsync();
Console.WriteLine($"{company.Name} ({company.Currency})");

For automatic token refresh within a session:

using var client = new FreeAgentClient(oauthClient, token, environment);
var company = await client.Company.GetCompanyAsync();

Always dispose the client when finished (using recommended).

Next steps

  • Pagination - list contacts and other paginated resources
  • Error handling - catch typed exceptions
  • API coverage - browse the SDK reference for every implemented resource
  • Contacts - list filters, CRUD methods, and the Contact model
  • Sample app - interactive Blazor workbench (contributors)