Lightstep User Management API Guide

Auth method: API Key (Bearer Token)

Setup steps

1. Log in to the Lightstep web UI as an Organization Admin.
2. Navigate to Organization Settings > API Keys.
3. Create a new API key and copy the token value.
4. Include the token in all API requests as: Authorization: bearer

List Users (SCIM)

• Method: GET
• URL: https://api.lightstep.com/scim/v2/Users
• Watch out for: SCIM token is separate from the general API key; generate it in Organization Settings under SCIM provisioning.

Request example

GET /scim/v2/Users
Authorization: bearer <SCIM_TOKEN>

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "Resources": [{"id":"abc123","userName":"user@example.com","active":true}]
}

Get User (SCIM)

• Method: GET
• URL: https://api.lightstep.com/scim/v2/Users/{id}
• Watch out for: User ID is Lightstep-internal; map it from the List response.

Request example

GET /scim/v2/Users/abc123
Authorization: bearer <SCIM_TOKEN>

Response example

{
  "id": "abc123",
  "userName": "user@example.com",
  "active": true,
  "name": {"givenName": "Jane", "familyName": "Doe"}
}

Create User (SCIM)

• Method: POST
• URL: https://api.lightstep.com/scim/v2/Users
• Watch out for: Requires Enterprise plan. User receives an invitation email upon creation.

Request example

POST /scim/v2/Users
Authorization: bearer <SCIM_TOKEN>
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"newuser@example.com",
  "active":true
}

Response example

{
  "id": "xyz789",
  "userName": "newuser@example.com",
  "active": true
}

Update User (SCIM PATCH)

• Method: PATCH
• URL: https://api.lightstep.com/scim/v2/Users/{id}
• Watch out for: Setting active=false deactivates the user but does not delete the account.

Request example

PATCH /scim/v2/Users/xyz789
Authorization: bearer <SCIM_TOKEN>
{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations":[{"op":"replace","path":"active","value":false}]
}

Response example

{
  "id": "xyz789",
  "userName": "newuser@example.com",
  "active": false
}

Delete User (SCIM)

• Method: DELETE
• URL: https://api.lightstep.com/scim/v2/Users/{id}
• Watch out for: Permanent deletion; cannot be undone. Prefer PATCH active=false for soft deactivation.

Request example

DELETE /scim/v2/Users/xyz789
Authorization: bearer <SCIM_TOKEN>

Response example

HTTP 204 No Content

List Groups (SCIM)

• Method: GET
• URL: https://api.lightstep.com/scim/v2/Groups
• Watch out for: Group support scope may be limited; verify with Lightstep/ServiceNow support given sunset status.

Request example

GET /scim/v2/Groups
Authorization: bearer <SCIM_TOKEN>

Response example

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults":1,
  "Resources":[{"id":"grp1","displayName":"Admins"}]
}

• Rate limits: Rate limit details are not explicitly documented in official Lightstep public API docs.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate limit documentation found. Given sunset timeline (March 2026), documentation may not be updated.

• Pagination method: cursor

• Default page size: Not documented

• Max page size: Not documented

• Pagination pointer: cursor

• Webhooks available: No

• Webhook notes: No user-management webhook events are documented in official Lightstep API or SCIM documentation.

• Alternative event strategy: Poll SCIM /Users endpoint for user state changes.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.lightstep.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, GET /Groups/{id}

Limitations:

• Requires Enterprise plan.
• SCIM token must be generated separately from the general API key in Organization Settings.
• Lightstep is being sunset in March 2026; migrating to ServiceNow Cloud Observability. SCIM configuration may need to be re-established in the new platform.
• IdP-specific SCIM connector documentation (Okta, Entra, etc.) is not confirmed in official Lightstep docs.
• Full Group provisioning support is not explicitly confirmed in available documentation.

Three scenarios are relevant for teams building against this API.

First, provisioning: POST to /scim/v2/Users with userName (email), name fields, and active: true;

store the returned id immediately, as it is Lightstep-internal and required for all subsequent PATCH or DELETE calls.

Second, deprovisioning: prefer PATCH /scim/v2/Users/{id} with active: false over DELETE - PATCH is reversible, DELETE is permanent and undocumented in terms of resource reassignment behavior.

Third, and most urgent: migrate the SCIM integration to ServiceNow Cloud Observability before March 2026.

The new platform's SCIM endpoint and bearer token are not yet fully public;

engage vendor support early, update the IdP connector base URL and token, and re-validate provisioning and deprovisioning flows before the cutoff.

Group provisioning support via /scim/v2/Groups is not explicitly confirmed in available documentation - verify scope with ServiceNow support before building group-sync logic into an identity graph pipeline.

Provision a new user via SCIM

1. Generate a SCIM bearer token in Lightstep Organization Settings (Enterprise plan required).
2. POST to https://api.lightstep.com/scim/v2/Users with userName (email), name fields, and active=true.
3. Store the returned id for future PATCH or DELETE operations.
4. User receives an invitation email to complete account setup.

Watch out for: Ensure the email domain is allowed in your Lightstep organization settings, or provisioning may fail silently.

Deprovision a user (soft deactivation)

1. Retrieve the user's SCIM id via GET /scim/v2/Users?filter=userName eq "user@example.com".
2. Send PATCH /scim/v2/Users/{id} with Operations: [{op: replace, path: active, value: false}].
3. Confirm the response shows active: false.

Watch out for: PATCH deactivation is reversible; DELETE is permanent. Prefer PATCH for offboarding workflows where account recovery may be needed.

Migrate SCIM integration to ServiceNow Cloud Observability before March 2026 sunset

1. Audit existing SCIM token and provisioned users in Lightstep Organization Settings.
2. Contact ServiceNow/Lightstep support to obtain ServiceNow Cloud Observability SCIM endpoint and new token.
3. Update IdP SCIM connector base URL and bearer token to point to the new ServiceNow Cloud Observability endpoint.
4. Re-test user provisioning and deprovisioning flows in the new platform before the March 2026 cutoff.

Watch out for: ServiceNow Cloud Observability SCIM endpoint and configuration details are not yet fully documented publicly; engage vendor support early.

The primary trap is building a durable SCIM integration against api.lightstep.com endpoints that will be invalidated at the March 2026 sunset.

Any identity graph that maps Lightstep user state - active flags, group memberships, internal SCIM id values - will need to be re-keyed against ServiceNow Cloud Observability identifiers post-migration, and the mapping between old and new IDs is not documented.

A secondary trap is token confusion: using the general API key where a SCIM-specific bearer token is required will produce auth failures that are not obviously self-explanatory from the error response. The absence of webhook support means there is no push-based signal for user state changes;

any identity graph relying on Lightstep user data must poll GET /scim/v2/Users and diff state client-side.