Getting started

This page takes you from zero to a successful authenticated GET against your tenant. It assumes you already have an Auradonors workspace; if not, sign up at auradonors.com first.

Prerequisites

You will need:

• A tenant. Either your production tenant (https://app.auradonors.com) or its sandbox sibling. Sandbox is recommended while you build.
• A user account with the tenant-settings:manage permission. Only that permission can provision API keys. Most tenant administrators have it by default.
• The api-access:enabled feature flag enabled for your tenant. Without it every API key is rejected at the auth layer with a 401. Toggle it under Administration → Tenant Settings → Features if it’s not already on.

1. Pick a base URL

Environment	Base URL
Production	https://api.auradonors.com
Sandbox	https://api-dev.auradonors.com

Every request goes against {baseUrl}/api/tenants/{tenantId}/.... The tenantId is a Guid you’ll find in the workspace URL after you sign in (https://app.auradonors.com/?tenantId={guid}), or in the Administration → Tenant Settings page.

2. Provision an API key

1. Sign in as a user with tenant-settings:manage.
2. Navigate to Administration → Integrations → API Keys.
3. Click Create API key, give it a name (something specific — nightly-export-job beats integration), and select the permission scopes the key needs. Match scopes to the permissions catalog.
4. The plaintext key is shown exactly once in the response. Copy it into your secret manager immediately. You cannot retrieve it later — if you lose it, revoke the key and create a new one.

The create-response shape:

{
  "id": "8a4f1c7b-3d6e-4f12-9a01-8b8d2c3e4f56",
  "name": "nightly-export-job",
  "keyPrefix": "ak_live_8a4f",
  "plainTextKey": "ak_live_8a4f1c7b3d6e4f129a018b8d2c3e4f56...",
  "scopes": ["contacts:view", "donations:view"],
  "expiresAt": null
}

The server stores only a SHA-256 hash of plainTextKey. Subsequent calls to GET /api/tenants/{tenantId}/api-keys return the metadata + keyPrefix only; the plaintext is never echoed back.

3. Send your first request

Set the key as an environment variable so it doesn’t end up in shell history:

export AURA_API_KEY="ak_live_..."
export TENANT_ID="00000000-0000-0000-0000-000000000000"

Then list the first page of contacts:

curl -sS \
  -H "X-Api-Key: $AURA_API_KEY" \
  "https://api.auradonors.com/api/tenants/$TENANT_ID/contacts?page=1&pageSize=5"

A successful response is HTTP 200 with a paginated envelope:

{
  "items": [
    {
      "id": 1,
      "contactType": "Individual",
      "firstName": "Jane",
      "lastName": "Donor",
      "primaryEmail": "[email protected]",
      "isActive": true
    }
  ],
  "totalCount": 1834,
  "page": 1,
  "pageSize": 5
}

If the call fails, the body is an RFC 7807 ProblemDetails document. The most common failures on a first attempt:

Status	Meaning
401	Header missing, key wrong, tenant lacks api-access:enabled, or the key has expired or been revoked. The body is generic — the API never tells you which case it was.
403	The key authenticated, but its scopes don’t cover this endpoint. Add the missing scope and rotate.
404	The tenantId in the URL doesn’t match the key’s tenant. Keys are per-tenant; check the URL first.

4. Where to next

• Authentication — scope grammar, key rotation, revocation, and the rejection model in detail.
• Conventions — pagination, error envelope, idempotency, and rate limits across every endpoint.
• Resources — the curated public-API surface, grouped by domain.
• Recipes — five end-to-end workflows showing how the endpoints compose.
• Live API explorer — every operation, request, and response shape, calling against the production OpenAPI feed.