Profile Provisioning & Administration

A profile is a user inside one organization. This page covers its whole lifecycle: how it gets created, what you can change, and what happens when the user leaves. Rights are only mentioned where they touch the lifecycle; see Access Rights Attribution for the details.

🚧
Do not confuse profile and user. A user is a physical person who can have profiles in several Izix organizations. Integrations work at profile level.

Three ways to provision automatically

	API	Directory sync (SCIM)	Just-in-time (SSO)
Source of truth	Your system	The customer's directory (for example Entra ID or Okta)	The identity provider, at first sign-in
Who builds	You, against the Public API	Nobody: configured on the organization	Nobody: option on the SSO connection, off by default
Creates and removes profiles	Yes	Yes, following the directory	Creates only
Sets plates, tags, language	Yes	No	No
Fits when	You own the user base, or need plates and tags from your data	The customer already manages its people in a directory	Users should simply appear when they first open the Izix web app

The three can be combined on one organization, with a rule: identity fields belong to the system that created the profile.

With directory sync, profile_external_reference, email, first_name and last_name cannot be changed through the API, and PUT /profiles/{externalId} is rejected. PATCH /profiles still works for plates, tags, language and phones.
With an SSO connection, email cannot be changed through the API and PUT is rejected.
A profile created just-in-time gets the organization's default access rights until an administrator or your system assigns specific ones. See Matching users to profiles.

Each profile returned by the API carries organization.is_organization_using_directory_sync and organization.is_organization_using_sso_connection, so your code can know which rule applies.

Lifecycle through the API

sequenceDiagram
    autonumber
    participant P as Your system
    participant API as Izix Public API
    P->>API: POST /oauth/token (client_credentials)
    API-->>P: access_token
    P->>API: POST /profiles (up to 50 per call)
    API-->>P: 201 profile_ids, or 207 with per-item errors
    Note over P,API: Rights: automatic through tags or default rights, or explicit with POST /access-rights
    P->>API: PATCH /profiles (tags, plates, names)
    API-->>P: 200
    P->>API: DELETE /profiles/{externalId}
    API-->>P: 204

Scopes: profiles.read, profiles.create, profiles.update, profiles.delete, and profiles.invite if you send invitations. Pass organization_id on every call when your credentials manage several organizations.

Identify your users

Attribute	Role
`profile_external_reference`	Your identifier for the user. All profile routes accept it as `{externalId}`. Prefer a stable ID over an email address
`email`	Required. Also the attribute used to match a user signing in through SSO with their profile, so keep it identical to what the identity provider sends
`plates`	Licence plates recognized by ANPR cameras at the gate. Letters, digits and ä ö ü Ä Ö Ü ß only
`tags`	Labels that can trigger automatic rights attribution, if the administrator configured it
`language`	Language of the Izix interface and notifications
`code`, `qr_code`	Credentials generated by Izix for keypads and QR readers, read-only

Create

POST /profiles takes a batch of up to 50 profiles with first_name, last_name and email. The response is 201 when all were created, 207 when some failed (errors lists them by their index in the request, resend only those), 413 above 50 items.

Creating a profile grants nothing. The profile needs at least one access right to book or enter: either the organization's default rights, rights linked to the tags you set, or an explicit POST /access-rights. See Access Rights Attribution.

Invite, or not

Izix emails a user only when you call POST /profiles/{externalId}/invite. If the user will receive many rights, assign them first to limit emails. If users reach Izix through your own app, do not invite them, so they are not pushed towards a separate login.

Update

PATCH /profiles updates several profiles at once. Identify each with profile_external_reference or email, put the changes in attributes. Use it for tags, plates, names and language, within the rules above. PUT /profiles/{externalId} replaces a whole profile and is only available on organizations without SSO or directory sync.

Remove

DELETE /profiles/{externalId} removes the profile: future reservations are deleted, past sessions are kept anonymized. To keep the user but end an access, update or delete the right instead, see Access Rights Attribution.

Deactivating the user in your identity provider is not enough. Plates and rights stay valid in Izix, so the plate can still open the barrier, until the profile or its rights are removed.

Keeping in sync

Izix does not send webhooks. Reconcile periodically: GET /profiles with filters[profile_external_references][] or filters[emails][], compared with your own user base. Send an Idempotency-Key header on writes (see Idempotency Keys); the API does not enforce it yet, so check with GET /profiles before retrying a failed creation. On 429, retry with exponential backoff.