Upgrade Guide: User Invitation APIs (users-srv → useractions-srv)

This guide covers the deprecation of three User Invitation APIs and their replacements. It includes changes in Authorization, RequestBody, RequestPath, and Response. Follow this guide to ensure a seamless transition to the new endpoints in version 3.103 (June).

Deprecated → Replacement (overview):

Deprecated	Replacement
POST users-srv/invite/initiate	POST useractions-srv/invitations
POST users-srv/invite/reinitiate/{{inviteId}}	PATCH useractions-srv/invitations/{{inviteId}}
GET users-srv/invite/info/{{inviteId}}	GET useractions-srv/invitations/{{inviteId}}

---

Deprecation Warning in Public Logs

From version 3.102, deprecation warnings are logged (warn level, internal_use = false) for the following:

• Initiate:
  DEPRECATION WARNING: The API users-srv/invite/initiate will be replaced by useractions-srv/invitations. Please ensure that you are replacing the API. Please find all details and guidances in our documentation https://docs.cidaas.com/ and under our Release Notes: Search Platform

• Reinitiate:
  DEPRECATION WARNING: The API users-srv/invite/reinitiate/{{inviteId}} will be replaced by useractions-srv/invitations/{{inviteId}}. Please ensure that you are replacing the API. Please find all details and guidances in our documentation https://docs.cidaas.com/ and under our Release Notes: Search Platform

• Invite info:
  DEPRECATION WARNING: The API users-srv/invite/info/{{inviteId}} will be replaced by useractions-srv/invitations/{{inviteId}}. Please ensure that you are replacing the API. Please find all details and guidances in our documentation https://docs.cidaas.com/ and under our Release Notes: Search Platform

Breaking change: The old APIs will be fully replaced in version 3.103 (June).

---

1. Initiate Invitation

Documentation: Invite a User

1.1 Authorization Changes

Deprecated:

• Scope: cidaas:admin_write

Replacement:

• Method: OAuth 2.0
• Steps:
  1. Obtain a token from the /token-srv/token endpoint.
  2. Use the token in the header: Authorization: Bearer <access_token>
• Scope: cidaas:users_invite

1.2 Request Body Changes

Deprecated:
Form-encoded data with fields such as invited_email, invited_name, invited_family_name, redirect_uri, response_type.

Replacement:
JSON structure. Field mapping:

Deprecated	Replacement
invited_email	email
invited_name	given_name
invited_family_name	family_name

Example (replacement):

{
  "email": "[email protected]",
  "given_name": "John",
  "family_name": "Doe",
  "allow_same_email": true,
  "client_id": "client",
  "client_name": "clientName",
  "redirect_uri": "https://test.com",
  "response_type": "token",
  "userGroups": [
    {
      "groupId": "groupA",
      "roles": ["roleA"]
    }
  ],
  "customFields": {
    "testCF": "testfield"
  },
  "params": {
    "testid": "test"
  }
}

Recommended approach

For a standard PKCE flow, use initiate_login_uri instead of response_type and redirect_uri. Your app can then start the authorization call and add invite_id as a query parameter.

1.3 Request Path Changes

Deprecated:
POST users-srv/invite/initiate

Replacement:
POST useractions-srv/invitations

1.4 Response Changes

See Invite a User for the full response schema. Success (201) returns data.id as the invitation identifier (invite_id). Status codes include 201, 400, 401, 409, 417.

---

2. Reinitiate / Change Invitation State

Documentation: Change Invitation State

2.1 Authorization Changes

Deprecated:

• Scope: cidaas:admin_write

Replacement:

• Method: OAuth 2.0
• Steps:
  1. Obtain a token from the /token-srv/token endpoint.
  2. Use the token in the header: Authorization: Bearer <access_token>
• Scope: cidaas:users_invite

2.2 Request Body Changes

Deprecated:
No body (or previous form-encoded usage).

Replacement:
JSON. Use either email or mobile identifier:

• For email:

{
  "state": "reinitiated",
  "used_email": "[email protected]"
}

• For mobile:

{
  "state": "reinitiated",
  "used_mobile_number": "+4917378948090333"
}

Invitation states: initiated, reinitiated, accepted, revoked, rejected. See Invite User for the full state table.

2.3 Request Path Changes

Deprecated:
POST users-srv/invite/reinitiate/{{inviteId}}

Replacement:
PATCH useractions-srv/invitations/{{inviteId}}

2.4 Response Changes

See Change Invitation State for the response format and status codes.

---

3. Invite Info / Prefill (Retrieve Invitation)

Documentation: Retrieving user invitation details by invite id

3.1 Authorization Changes

Deprecated:
(Depends on previous configuration; document if your integration used a specific method.)

Replacement:
No authentication required for the replacement endpoint (public endpoint for prefilling registration forms). See the documentation for your deployment if this differs.

3.2 Request Body Changes

Deprecated:
No body (GET).

Replacement:
No body (GET).

3.3 Request Path Changes

Deprecated:
GET users-srv/invite/info/{{inviteId}}

Replacement:
GET useractions-srv/invitations/{{inviteId}}

3.4 Response Changes

See the documentation links above for the response schema (e.g. pre-filled invitation data). Status codes include 200, 204, 400, 401, 404.

---

4. Upgrade Checklist

1. Audit your code: Find all usages of the deprecated APIs (users-srv/invite/initiate, users-srv/invite/reinitiate/{{inviteId}}, users-srv/invite/info/{{inviteId}}).
2. Update authorization: Use OAuth 2.0 with scope cidaas:users_invite where required (initiate and reinitiate).
3. Update request paths and bodies: Use the new paths and JSON payloads as described above.
4. Update response handling: Align your application with the new response formats (see linked documentation).
5. Test in staging: Validate the new endpoints in a non-production environment.
6. Monitor: After upgrading, monitor logs and behavior for any issues.

---

5. Timeline

Date / Version	Action
29 Feb	Deprecation notice issued
3.102	Deprecation warnings logged (warn, from this version)
3.103 (June)	Breaking change: full transition to new APIs

---

6. Resources

• Documentation:
  • Invite a User
  • Change Invitation State (PATCH)
  • Retrieving user invitation details by invite id (GET)
  • Release Notes (Search Platform)
• Support: [email protected]

---

7. Email Draft for Customer Communication

You can use the following text when notifying customers:

Subject (example): Deprecation of User Invitation APIs (users-srv) — action required by 3.103

Body:

We are deprecating the following User Invitation APIs and replacing them with new endpoints. Please plan your migration before version 3.103 (June), when the old APIs will no longer be available.

Deprecated → Replacement:

• POST users-srv/invite/initiate → POST useractions-srv/invitations
• POST users-srv/invite/reinitiate/{{inviteId}} → PATCH useractions-srv/invitations/{{inviteId}}
• GET users-srv/invite/info/{{inviteId}} → GET useractions-srv/invitations/{{inviteId}}

Upgrade guide (details, request/response changes, timeline):
[Insert link to this upgrade guide, e.g. https://docs.cidaas.com/docs/integration-doc/upgrade-guides/upgrade-guide-invite-apis]

For questions, contact [email protected].