Skip to content

Latest commit

 

History

History
211 lines (146 loc) · 30.6 KB

README.md

File metadata and controls

211 lines (146 loc) · 30.6 KB

Invitations

Overview

Available Operations

create

Creates a new invitation for the given email address and sends the invitation email. Keep in mind that you cannot create an invitation if there is already one for the given email address. Also, trying to create an invitation for an email address that already exists in your application will result to an error.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.invitations.create(request={
        "email_address": "[email protected]",
        "public_metadata": {

        },
        "redirect_url": "https://example.com/welcome",
        "expires_in_days": 177398,
        "template_slug": clerk_backend_api.TemplateSlug.INVITATION,
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
request models.CreateInvitationRequestBody ✔️ The request object to use for the request.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Invitation

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 422 application/json
models.SDKError 4XX, 5XX */*

list

Returns all non-revoked invitations for your application, sorted by creation date

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.invitations.list(status=clerk_backend_api.ListInvitationsQueryParamStatus.ACCEPTED, query="<value>", order_by="pending", paginated=False, limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
status Optional[models.ListInvitationsQueryParamStatus] ➖ Filter invitations based on their status
query Optional[str] ➖ Filter invitations based on their email_address or id
order_by Optional[str] ➖ Allows to return invitations in a particular order.
At the moment, you can order the returned invitations either by their created_at, email_address or expires_at.
In order to specify the direction, you can use the +/- symbols prepended in the property to order by.
For example, if you want 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.		 pending
paginated Optional[bool] ➖ Whether to paginate the results.
If true, the results will be paginated.
If false, the results will not be paginated.
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.

Response

List[models.Invitation]

Errors

Error Type Status Code Content Type
models.SDKError 4XX, 5XX */*

bulk_create

Use this API operation to create multiple invitations for the provided email addresses. You can choose to send the invitations as emails by setting the notify parameter to true. There cannot be an existing invitation for any of the email addresses you provide unless you set ignore_existing to true for specific email addresses. Please note that there must be no existing user for any of the email addresses you provide, and this rule cannot be bypassed.

This endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.invitations.bulk_create(request=[
        {
            "email_address": "[email protected]",
            "public_metadata": {
                "key": "<value>",
            },
            "redirect_url": "https://devoted-government.net",
            "expires_in_days": 606004,
        },
        {
            "email_address": "[email protected]",
            "public_metadata": {
                "key": "<value>",
            },
            "redirect_url": "https://devoted-government.net",
            "expires_in_days": 606004,
        },
    ])

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
request List[models.RequestBody] ✔️ The request object to use for the request.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

List[models.Invitation]

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 422 application/json
models.SDKError 4XX, 5XX */*

revoke

Revokes the given invitation. Revoking an invitation will prevent the user from using the invitation link that was sent to them. However, it doesn't prevent the user from signing up if they follow the sign up flow. Only active (i.e. non-revoked) invitations can be revoked.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.invitations.revoke(invitation_id="inv_123")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
invitation_id str ✔️ The ID of the invitation to be revoked inv_123
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.InvitationRevoked

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 404 application/json
models.SDKError 4XX, 5XX */*