(organization_invitations)
- get_all - Get a list of organization invitations for the current instance
- create - Create and send an organization invitation
- list - Get a list of organization invitations
- bulk_create - Bulk create and send organization invitations
list_pending- Get a list of pending organization invitations⚠️ Deprecated- get - Retrieve an organization invitation by ID
- revoke - Revoke a pending organization invitation
This request returns the list of organization invitations for the instance.
Results can be paginated using the optional limit
and offset
query parameters.
You can filter them by providing the 'status' query parameter, that accepts multiple values.
You can change the order by providing the 'order' query parameter, that accepts multiple values.
You can filter by the invited user email address providing the query
query parameter.
The organization invitations are ordered by descending creation date by default.
import clerk_backend_api
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.get_all(limit=20, offset=10, order_by="-created_at", status=clerk_backend_api.ListInstanceOrganizationInvitationsQueryParamStatus.ACCEPTED, query="<value>")
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
limit |
Optional[int] | ➖ | Applies a limit to the number of results returned. Can be used for paginating the results together with offset . |
20 |
offset |
Optional[int] | ➖ | Skip the first offset results when paginating.Needs to be an integer greater or equal to zero. To be used in conjunction with limit . |
10 |
order_by |
Optional[str] | ➖ | Allows to return organization invitations in a particular order. At the moment, you can order the returned organization invitations either by their created_at or email_address .In order to specify the direction, you can use the +/- symbols prepended in the property to order by.For example, if you want organization invitations to be returned in descending order according to their created_at property, you can use -created_at .If you don't use + or - , then + is implied.Defaults to -created_at . |
|
status |
Optional[models.ListInstanceOrganizationInvitationsQueryParamStatus] | ➖ | Filter organization invitations based on their status | |
query |
Optional[str] | ➖ | Filter organization invitations based on their email_address |
|
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
models.OrganizationInvitationsWithPublicOrganizationData
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 404, 422, 500 | application/json |
models.SDKError | 4XX, 5XX | */* |
Creates a new organization invitation and sends an email to the provided email_address
with a link to accept the invitation and join the organization.
You can specify the role
for the invited organization member.
New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee.
The request body supports passing an optional redirect_url
parameter.
When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided.
Use this parameter to implement a custom invitation acceptance flow.
You can specify the ID of the user that will send the invitation with the inviter_user_id
parameter.
That user must be a member with administrator privileges in the organization.
Only "admin" members can create organization invitations.
You can optionally provide public and private metadata for the organization invitation. The public metadata are visible by both the Frontend and the Backend whereas the private ones only by the Backend. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.create(organization_id="org_12345", email_address="[email protected]", role="admin", inviter_user_id="user_67890", public_metadata={
"key": "value",
}, private_metadata={
"private_key": "secret_value",
}, redirect_url="https://example.com/welcome")
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
organization_id |
str | ✔️ | The ID of the organization for which to send the invitation | org_12345 |
email_address |
str | ✔️ | The email address of the new member that is going to be invited to the organization | [email protected] |
role |
str | ✔️ | The role of the new member in the organization | admin |
inviter_user_id |
OptionalNullable[str] | ➖ | The ID of the user that invites the new member to the organization. Must be an administrator in the organization. |
user_67890 |
public_metadata |
Dict[str, Any] | ➖ | Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API. | { "key": "value" } |
private_metadata |
Dict[str, Any] | ➖ | Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. | { "private_key": "secret_value" } |
redirect_url |
Optional[str] | ➖ | Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email. | https://example.com/welcome |
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 403, 404, 422 | application/json |
models.SDKError | 4XX, 5XX | */* |
This request returns the list of organization invitations.
Results can be paginated using the optional limit
and offset
query parameters.
You can filter them by providing the 'status' query parameter, that accepts multiple values.
The organization invitations are ordered by descending creation date.
Most recent invitations will be returned first.
Any invitations created as a result of an Organization Domain are not included in the results.
import clerk_backend_api
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.list(organization_id="org_12345", limit=20, offset=10, status=clerk_backend_api.ListOrganizationInvitationsQueryParamStatus.PENDING)
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
organization_id |
str | ✔️ | The organization ID. | org_12345 |
limit |
Optional[int] | ➖ | Applies a limit to the number of results returned. Can be used for paginating the results together with offset . |
20 |
offset |
Optional[int] | ➖ | Skip the first offset results when paginating.Needs to be an integer greater or equal to zero. To be used in conjunction with limit . |
10 |
status |
Optional[models.ListOrganizationInvitationsQueryParamStatus] | ➖ | Filter organization invitations based on their status | pending |
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
models.OrganizationInvitations
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 404 | application/json |
models.SDKError | 4XX, 5XX | */* |
Creates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the organization.
You can specify a different role
for each invited organization member.
New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee.
The request body supports passing an optional redirect_url
parameter for each invitation.
When the invited user clicks the link to accept the invitation, they will be redirected to the provided URL.
Use this parameter to implement a custom invitation acceptance flow.
You can specify the ID of the user that will send the invitation with the inviter_user_id
parameter. Each invitation
can have a different inviter user.
Inviter users must be members with administrator privileges in the organization.
Only "admin" members can create organization invitations.
You can optionally provide public and private metadata for each organization invitation. The public metadata are visible
by both the Frontend and the Backend, whereas the private metadata are only visible by the Backend.
When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.bulk_create(organization_id="org_12345", request_body=[
{
"email_address": "[email protected]",
"role": "admin",
"inviter_user_id": "user_67890",
"public_metadata": {
},
"private_metadata": {
},
"redirect_url": "https://example.com/welcome",
},
])
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
organization_id |
str | ✔️ | The organization ID. | org_12345 |
request_body |
List[models.RequestBody] | ✔️ | N/A | |
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
models.OrganizationInvitations
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 403, 404, 422 | application/json |
models.SDKError | 4XX, 5XX | */* |
This request returns the list of organization invitations with "pending" status.
These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet.
Results can be paginated using the optional limit
and offset
query parameters.
The organization invitations are ordered by descending creation date.
Most recent invitations will be returned first.
Any invitations created as a result of an Organization Domain are not included in the results.
⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.list_pending(organization_id="org_12345", limit=20, offset=10)
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
organization_id |
str | ✔️ | The organization ID. | org_12345 |
limit |
Optional[int] | ➖ | Applies a limit to the number of results returned. Can be used for paginating the results together with offset . |
20 |
offset |
Optional[int] | ➖ | Skip the first offset results when paginating.Needs to be an integer greater or equal to zero. To be used in conjunction with limit . |
10 |
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
models.OrganizationInvitations
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 404 | application/json |
models.SDKError | 4XX, 5XX | */* |
Use this request to get an existing organization invitation by ID.
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.get(organization_id="org_123456789", invitation_id="inv_987654321")
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
organization_id |
str | ✔️ | The organization ID. | org_123456789 |
invitation_id |
str | ✔️ | The organization invitation ID. | inv_987654321 |
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 403, 404 | application/json |
models.SDKError | 4XX, 5XX | */* |
Use this request to revoke a previously issued organization invitation.
Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation.
Only organization invitations with "pending" status can be revoked.
The request accepts the requesting_user_id
parameter to specify the user which revokes the invitation.
Only users with "admin" role can revoke invitations.
from clerk_backend_api import Clerk
with Clerk(
bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:
res = clerk.organization_invitations.revoke(organization_id="org_123456", invitation_id="inv_123456", requesting_user_id="usr_12345")
assert res is not None
# Handle response
print(res)
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
organization_id |
str | ✔️ | The organization ID. | org_123456 |
invitation_id |
str | ✔️ | The organization invitation ID. | inv_123456 |
requesting_user_id |
OptionalNullable[str] | ➖ | The ID of the user that revokes the invitation. Must be an administrator in the organization. |
usr_12345 |
retries |
Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Error Type | Status Code | Content Type |
---|---|---|
models.ClerkErrors | 400, 403, 404 | application/json |
models.SDKError | 4XX, 5XX | */* |