docs / 02
Authentication & credits
Two credentials: a session cookie for account and token management, and a bearer token for metered data access. The unit is always 1 credit = 1 parcel record.
Session authentication
Account and token management use the Better Auth session cookie. Sign up, sign in and sign out through the endpoints under /api/auth (for example POST /api/auth/sign-up/email and POST /api/auth/sign-in/email). GET /api/me returns the current session as JSON, or 401 with { "user": null } when signed out.
curl https://parcel.reeeally.ai/api/me \
-H "Cookie: $SESSION_COOKIE"Bearer token authentication
The data endpoints require an API token in the Authorization header. Tokens are created from the console or the token endpoints below and are scoped to one account.
Authorization: Bearer pk_trial_...Pricing and the credit unit
| Plan | Price | Included | Overage |
|---|---|---|---|
| API Sandbox Trial | Free, 30 days | 50 records | — |
| API Records | $59/month | 4,000 records | $0.05 per record |
1 credit = 1 parcel record, consistently across the trial, the included monthly grant and overage. A request is only metered for the records it actually returns.
Token lifecycle
| Endpoint | Auth | Purpose |
|---|---|---|
| POST /api/tokens/trial | session | Issue the 30-day trial token (50 credits). |
| GET /api/tokens | session | List the account's tokens. Raw values and hashes never appear. |
| POST /api/tokens/:id/revoke | session | Revoke a token immediately. |
curl -X POST https://parcel.reeeally.ai/api/tokens/trial \
-H "Cookie: $SESSION_COOKIE"curl https://parcel.reeeally.ai/api/tokens \
-H "Cookie: $SESSION_COOKIE"curl -X POST https://parcel.reeeally.ai/api/tokens/TOKEN_ID/revoke \
-H "Cookie: $SESSION_COOKIE"How metering works
- Trial tokens start at 50 credits and expire 30 days after issue. Once the credits are used, the token is rejected with 402.
- Paid tokens include 4,000 records per monthly period. Records beyond the included amount accrue overage at $0.05 each and are recorded in the ledger for billing.
- Paid tokens stay valid after the included grant is exhausted; further reads are billed as overage.
- Each metered response includes a metering block with the plan, remaining credits and overage.
Token rejection
| Condition | HTTP | error |
|---|---|---|
| No Authorization header | 401 | missing |
| Token not recognised | 401 | invalid |
| Token past its expiry | 401 | expired |
| Trial token out of credits | 402 | exhausted |
| Token revoked | 403 | revoked |
Only the SHA-256 hash of a token is stored. The raw value is returned exactly once at issue, so a lost token must be revoked and replaced.