User Provisioning

The POST /api/v1/users/invite endpoint creates or looks up a user in your Align workspace. Integration partners use it to provision team members during onboarding flows.

Endpoint

POST /api/v1/users/invite
Authorization: Bearer <org-scoped-api-key>

Required permission: write:user (org-scoped key only — project-scoped keys cannot invite users)

Request Body

{
  "email": "alice@example.com",      // required
  "name": "Alice Smith",             // required
  "role": "developer",               // optional — defaults to "user"
  "projectIds": ["proj-uuid-..."],   // optional — add to specific projects on creation
  "sendInvite": true,                // optional — defaults to true; set false to suppress the welcome email
  "externalRef": {                   // optional — idempotency key from your system
    "provider": "illumera",
    "externalType": "member",
    "externalId": "illumera-member-42"
  },
  "metadata": {}                     // optional — arbitrary key/value stored on the user record
}

The `role` Field

Default value

If role is omitted, the user is created with role "user".

Valid values

Role	Description	Time approval routing
`user`	Standard team member. Can log time, comment, and view assigned projects. (default)	Submits; cannot approve
`client`	External stakeholder. Read-only access to projects they are added to.	No time access
`tester`	QA role. Can create and update bug entries; limited write access.	Submits; cannot approve
`developer`	Engineering contributor. Can link commits, manage entries, and log time.	Submits; cannot approve
`tech_lead`	Senior engineering role. Same as `developer` plus can review and close entries.	Submits; cannot approve
`product_owner`	Product management role. Can manage entries and releases across assigned projects.	Submits; cannot approve
`devops_engineer`	Infrastructure / CI role. Can manage releases and view CI evidence.	Submits; cannot approve
`manager`	Team lead. Can approve/reject time entries, manage project members, and view cost data.	Approves and rejects
`admin`	Organization administrator. Full access, including billing and API key management.	Full time management

Admin role assignment

admin is a valid role value in Align but cannot be set via this endpoint — it must be assigned manually in Settings → Team by an existing admin. Sending role: "admin" in the request body returns 403 forbidden_role. Provision the user with any other role, then promote them to admin in the UI.

Role escalation guard

If the email already exists in the workspace, the endpoint returns the existing user record without updating the role. This prevents accidental role escalation on re-invite. To change an existing user's role, an admin must update it in Settings → Team (the PATCH /api/v1/users/:id endpoint only updates name and metadata, not role).

Response

On creation (201 Created):

{
  "id": "user-uuid-...",
  "email": "alice@example.com",
  "name": "Alice Smith",
  "role": "developer",
  "organizationId": "org-uuid-...",
  "createdAt": "2026-05-26T09:00:00.000Z"
}

On conflict with an existing user (200 OK):

{
  "id": "user-uuid-...",
  "email": "alice@example.com",
  "name": "Alice Smith",
  "role": "developer",
  "organizationId": "org-uuid-...",
  "createdAt": "2025-01-15T12:00:00.000Z"
}

The 200 response signals that no new record was created. The existing user's role is unchanged.

Using `externalRef` for Idempotent Provisioning

Pass externalRef to make the call idempotent against your system's member ID. If you call the endpoint twice with the same externalRef, the second call returns the same user record without creating a duplicate:

curl -X POST https://app.alignsoft.us/api/v1/users/invite \
  -H "Authorization: Bearer $ALIGN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "Alice Smith",
    "role": "developer",
    "externalRef": {
      "provider": "illumera",
      "externalType": "member",
      "externalId": "illumera-member-42"
    }
  }'

The externalRef is stored in an integration_links row. You can verify consistency later using GET /api/v1/integration-links?provider=illumera&externalType=member.

Reconciliation

If you maintain a local copy of the user list, poll GET /api/v1/users nightly to catch any manual changes made inside Align (role changes, deactivations). See Reconciliation for the full polling guide.

Endpoint​

Request Body​

The role Field​

Default value​

Valid values​

Role escalation guard​

Response​

Using externalRef for Idempotent Provisioning​

Reconciliation​