ACaccessowl
users

Onboard a user

Changed on

Onboards the user via the Zero-Touch (access-template) flow: provisions the access the template rules match for the user's org info. Does not change the user — set org info and manager beforehand with PATCH /users/{user_id}; onboarding requires the user to have a manager. Omit scheduled_at to provision now; a future timestamp defers provisioning. Calling again for a user already onboarding reschedules the planned provisioning to the new scheduled_at (omit it to provision now); an onboarding already being provisioned can no longer be rescheduled.

post/api/v1/users/{user_id}/onboard

Request

  • Base URL
    https://app.accessowl.io
  • URL
    https://app.accessowl.io/api/v1/users/{user_id}/onboard
  • Auth
    HTTP bearer

Path parameters

user_idstring uuid required

User ID

Headers

Idempotency-Keystring

Optional key (1–255 chars) for safely retrying a request. Reusing the same key for the same request returns 409 Conflict and is not processed again — this confirms the request was already received. Keys are retained for 14 days.

Request body

scheduled_atstring date-time nullable

When to provision access. Omitted or null provisions now; a future ISO 8601 timestamp defers it. For a user already onboarding, this reschedules the planned provisioning.

Example request

{
  "scheduled_at": "2026-12-31T09:00:00Z"
}

Response

User onboarding triggered

deactivated_atstring date-time nullable

Deactivation timestamp

departmentsstring[]

Departments the user belongs to

emailstring email required

Email address

employment_type'full_time' | 'part_time' | 'contract' | 'freelance' | 'internship' | 'apprenticeship' | 'working_student' | 'training' nullable

Employment type

first_namestring required

First name

full_namestring

Full name (computed)

idstring uuid required

User ID

inserted_atstring date-time

Creation timestamp

job_titlestring nullable

Job title

last_namestring required

Last name

location_citystring nullable

City location

manager_user_idstring uuid nullable

Manager user ID

offboarding_scheduled_atstring date-time nullable

When the planned offboarding starts

onboarding_scheduled_atstring date-time nullable

When the planned onboarding starts provisioning

status'active' | 'inactive' | 'onboarding' | 'onboarding_provisioning_planned' | 'offboarding' | 'offboarding_planned' | 'offboarded' required

Current status

teamsstring[]

Teams the user belongs to

updated_atstring date-time

Last update timestamp

Example response

{
  "deactivated_at": null,
  "departments": [
    "Engineering"
  ],
  "email": "john@example.com",
  "employment_type": "full_time",
  "first_name": "John",
  "full_name": "John Doe",
  "id": "7488a646-e31f-11e4-aace-600308960662",
  "inserted_at": "2023-01-01T00:00:00Z",
  "job_title": "Software Engineer",
  "last_name": "Doe",
  "location_city": "San Francisco",
  "manager_user_id": null,
  "offboarding_scheduled_at": null,
  "onboarding_scheduled_at": null,
  "status": "active",
  "teams": [
    "Engineering",
    "Backend"
  ],
  "updated_at": "2023-01-01T00:00:00Z"
}

Changes

  • 5a1f071e40d8Revision changes
    • breaking

      response property errors/additionalProperties/items/ list-of-types was widened by adding types object to media type application/json of response 422

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      added the new forbidden enum value to the response property for the response status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

  • 1cc0fedf0bf8Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status