Skip to main content

Getting started

This guide walks through making your first authenticated request.

1. Get an API key​

API keys are minted from the Feathr app. Each key is opaque — Feathr stores only a hash of it, so the secret is shown once at creation and cannot be recovered afterward. Copy it somewhere safe.

A key looks like:

fthr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

When you create a key you also choose its scopes — the set of operations it may perform (for example persons:read or tags:write). Grant only the scopes the integration needs.

2. Make a request​

Send the key as a bearer token in the Authorization header:

curl https://api.feathr.co/me \
  -H "Authorization: Bearer $FEATHR_API_KEY"

GET /me returns the identity and scopes behind the key — a quick way to confirm your credentials work:

{
  "account_id": "5f8e...c21a",
  "scopes": ["persons:read", "tags:write"],
  "key_id": "6a1b...9f30"
}

3. Call an endpoint​

List the persons in your account. GET /persons requires at least one of updated_since, email, or external_id. Passing updated_since returns everyone last seen at or after that timestamp (no more than 30 days ago):

curl "https://api.feathr.co/persons?updated_since=2024-01-01T00:00:00Z&page=1&size=50" \
  -H "Authorization: Bearer $FEATHR_API_KEY"

The response is an offset-paginated Page envelope:

{
  "items": [{ "id": "...", "email": "..." }],
  "page": 1,
  "size": 50,
  "total": 327
}

Fetch the next page by incrementing page; you've read everything once page * size >= total.

Next steps​