Reference

v1

REST API

The sandbox API uses JSON over HTTPS. Server operations authenticate with a project secret; browser reads combine a publishable key with a short-lived identity token.

Base URL

https://our-impact.vercel.app Download OpenAPI

Authentication

CredentialPurpose
oi_sk_test_*Trusted server operations. Never send it to a browser.
oi_pk_test_*Safe project identifier used for browser reads.
Identity tokenShort-lived token scoped to one project and external user.
Server request
curl https://our-impact.vercel.app/api/v1/users/storefront%3Auser_01JABC/entitlements \
  --header "Authorization: Bearer $OUR_IMPACT_SECRET_KEY"

Endpoint index

All request and response field names use snake_case on the wire. The TypeScript SDKs map them to camelCase.

POST/api/v1/eventsSecret key

Create a verified event

Accepts a stable event ID, event type, external user ID, occurrence time, and free-form properties. Returns the supporter’s newly evaluated entitlements. Replaying the same event ID is safe.
POST/api/v1/identity-tokensSecret key

Create a browser identity token

Issues an opaque token for one external user. ttl_seconds accepts 60–3600 seconds and defaults to 900.
GET/api/v1/users/{externalUserId}/entitlementsSecret key

Read a supporter from your server

Returns the supporter profile and all current entitlement states using the stable user ID from your application.
GET/api/v1/me/entitlementsPublishable key + identity token

Read the current browser user

Returns only the supporter identified by the short-lived token. The request origin must be in the developer project’s allowed origins.

Create a verified event

POST /api/v1/events · Secret key · 201 on creation, 200 on replay

Request body
{
  "id": "donation_01JABC123",
  "type": "donation.completed",
  "external_user_id": "storefront:user_01JABC",
  "display_name": "Avery",
  "occurred_at": "2026-11-06T12:00:00Z",
  "properties": {
    "amount_minor": 5000,
    "currency": "USD",
    "organization_id": 42
  }
}
201 Created
{
  "id": "d85b1407-351d-4694-9ac2-9c88b415c8c6",
  "replayed": false,
  "entitlements": [
    {
      "entitlement_key": "community_champion",
      "state": "active",
      "qualifying_count": 1,
      "progress_value": 5000,
      "progress_unit": "usd",
      "qualified_at": "2026-11-06T12:00:01Z",
      "valid_until": null,
      "updated_at": "2026-11-06T12:00:01Z"
    }
  ]
}
Idempotency
The request id is unique within one project. Retry with the same ID.
Event type
type must match ^[a-z][a-z0-9_.]{2,79}$.
Currency
Send integer minor units plus an uppercase ISO currency code in properties.
SDK
client.events.createVerifiedEvent({ body })

Create an identity token

POST /api/v1/identity-tokens · Secret key · 200

Request body
{
  "external_user_id": "storefront:user_01JABC",
  "display_name": "Avery",
  "ttl_seconds": 900
}
200 OK
{
  "token": "oi_identity_opaque_value",
  "expires_at": "2026-11-06T12:15:00Z",
  "user": {
    "external_user_id": "storefront:user_01JABC",
    "display_name": "Avery"
  }
}

Read supporter entitlements

Use the secret-key route for server decisions and the identity route for browser experiences.

GET /api/v1/users/{externalUserId}/entitlements
curl "https://our-impact.vercel.app/api/v1/users/storefront%3Auser_01JABC/entitlements" \
  --header "Authorization: Bearer $OUR_IMPACT_SECRET_KEY"
GET /api/v1/me/entitlements
curl https://our-impact.vercel.app/api/v1/me/entitlements \
  --header "x-our-impact-key: oi_pk_test_..." \
  --header "Authorization: Bearer $IDENTITY_TOKEN" \
  --header "Origin: https://shop.example.com"
Server SDK
client.entitlements.listUserEntitlements({ externalUserId })
Browser SDK
impact.user.is(), get(), all(), and profile()
Origin policy
The browser route checks the exact request origin against the project’s allowed origins.
Not found
The server route returns 404 when the project has no supporter with that external ID.

SDK to API map

PackageMethodHTTP operationRuntime
@our-impact/nodeevents.createVerifiedEventPOST /api/v1/eventsTrusted server
@our-impact/nodeidentity.createIdentityTokenPOST /api/v1/identity-tokensTrusted server
@our-impact/nodeentitlements.listUserEntitlementsGET /api/v1/users/{externalUserId}/entitlementsTrusted server
@our-impact/browseruser.is / get / all / profileGET /api/v1/me/entitlementsAllowed browser origin

Response status codes

200Success or idempotent replay
201Verified event created
400Request validation failed
401Credential or identity is invalid
403Browser origin is not allowed
404Supporter was not found

Generated contract