Identity

Overview

The Identity module is the central directory for all human and legal entities within an Oblax application. It provides a unified API to manage people and organizations along with their dependent resources such as addresses, contact methods, preferences, roles, and bank accounts.

People are the individual users of your application. Organizations represent companies or legal entities. A person can belong to multiple organizations through a many-to-many relationship. Sub-resources such as addresses and contact methods are shared across both person and organization scopes.

Each top-level resource supports two creation paths. A simple create adds the resource with just its core fields. An onboard endpoint creates the resource together with its associated sub-resources (addresses, contact methods, preferences, and optionally bank accounts) in a single request, automatically promoting the first item in each collection to the primary position.

Before You Start

• Install the Oblax CLI (obx) and authenticate with obx login.
• For SDK usage, install the oblax npm package.
• For REST API access, obtain a valid JWT and a project app-id.
• Every request requires the Authorization: Bearer <token> header and the X-App-Id header. See the Authentication reference for details.

When to Use

• Register new users in your application during sign-up or invitation flows.
• Add organizations your application interacts with such as merchants, partners, or tenants.
• Store and retrieve addresses for shipping, billing, or location-based features.
• Manage contact channels like email and phone numbers for notifications or verification.
• Persist user or organization preferences for theming, locale, or feature flags.
• Assign platform or custom roles to people for authorization and access control.
• Link bank accounts to organizations for payouts, invoicing, or billing.
• Associate people with organizations to model memberships or employment.

How It Fits

    flowchart LR
    Auth[Auth] --> Identity[Identity]
    Identity --> Person[Person]
    Identity --> Organization[Organization]
    Person --> Address[Address]
    Person --> ContactMethod[ContactMethod]
    Person --> Preference[Preference]
    Person --> Role[Role]
    Organization --> Address
    Organization --> ContactMethod
    Organization --> Preference
    Organization --> BankAccount[BankAccount]
    Person <--> OrganizationPerson[OrganizationPerson] --> Organization
  

Works Well With

• Auth – Authenticates people and issues JWTs. Identity provides the person records that Auth accounts reference.
• Forms – Collects data submissions from identified people and organizations.
• Flux – Triggers event-driven workflows on person or organization lifecycle events such as creation or update.
• Templates – Renders personalized documents or communications using stored identity data.

Quick Example

The following example creates a person and an organization, links them, and adds an address and contact method under that person.

Creating a person and an organization

Create the two top-level identity records.

obx app identity:people init
obx app identity:people push init
obx app identity:organizations init
obx app identity:organizations push init

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { identity } from "@oblax/identity";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [identity()],
});

const person = await oblax.identity.person.create({
  first_name: "Jane",
  last_name: "Doe",
});

const org = await oblax.identity.organization.create({
  name: "Acme Corp",
  legal_name: "Acme Corporation Inc.",
});

POST /api/v1/identity/people

{
  "first_name": "Jane",
  "last_name": "Doe"
}

{
  "id": "ppl_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe"
}

POST /api/v1/identity/organizations

{
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc."
}

{
  "id": "org_abc123def789",
  "name": "Acme Corp",
  "legal_name": "Acme Corporation Inc."
}

Linking the person to the organization

Associate the person with the organization through a membership record.

obx app identity:people:organizations link --person-id ppl_abc123def456 --data org.json

await oblax.identity.organizationPerson.create({
  organization_id: "org_abc123def789",
  person_id: "ppl_abc123def456",
});

POST /api/v1/identity/people/ppl_abc123def456/organizations

{
  "organization_id": "org_abc123def789"
}

{
  "id": "olk_abc123def001",
  "organization_id": "org_abc123def789",
  "person_id": "ppl_abc123def456"
}

Adding an address and contact method

Enrich the person record with a home address and an email contact method.

obx app identity:people:addresses init
obx app identity:people:addresses push init --person-id ppl_abc123def456
obx app identity:people:contacts init
obx app identity:people:contacts push init --person-id ppl_abc123def456

await oblax.identity.address.create("ppl_abc123def456", {
  label: "Home",
  country: "US",
  city: "San Francisco",
  zipcode: "94105",
  address: "Market Street",
  address_number: "123",
  longitude: -122.39,
  latitude: 37.79,
});

await oblax.identity.contactMethod.create("ppl_abc123def456", {
  contact_type: "EMAIL",
  contact_kind: "PERSONAL",
  value: "jane.doe@example.com",
});

POST /api/v1/identity/people/ppl_abc123def456/addresses

{
  "label": "Home",
  "country": "US",
  "city": "San Francisco",
  "zipcode": "94105",
  "address": "Market Street",
  "address_number": "123",
  "longitude": -122.39,
  "latitude": 37.79
}

{
  "id": "addr_abc123def001",
  "label": "Home",
  "country": "US",
  "city": "San Francisco"
}

POST /api/v1/identity/people/ppl_abc123def456/contact-methods

{
  "contact_type": "EMAIL",
  "contact_kind": "PERSONAL",
  "value": "jane.doe@example.com"
}

{
  "id": "cm_abc123def002",
  "contact_type": "EMAIL",
  "contact_kind": "PERSONAL",
  "value": "jane.doe@example.com"
}

Errors

Best Practices

• Use the onboard endpoints to create a person or organization together with their sub-resources in a single request. Sub-resources are persisted atomically and the first item in each collection is automatically set as the primary.
• When setting a primary address, contact method, or bank account, set the primary flag on the relevant sub-resource. The service manages the owner’s primary pointer automatically.
• Enum fields such as contact_type, contact_kind, value_type, and size accept only the documented uppercase values. Lowercase or mixed-case values will be rejected.
• Use the SDK for type-safe resource construction. The SDK’s functional option pattern guarantees valid objects at build time.
• Sub-resources like addresses and contact methods support independent CRUD operations. You do not need to recreate the parent to update a child.
• Always include the X-App-Id and Authorization headers in REST requests. Missing headers result in 401 Unauthorized responses.
• The organization-person relationship is a hard link. Deleting the link does not affect the person or organization records themselves.

Related Modules

Auth, Forms, Flux, Templates