Skip to content

Latest commit

 

History

History
217 lines (152 loc) · 13.6 KB

README.md

File metadata and controls

217 lines (152 loc) · 13.6 KB

Invitations

(invitations)

Overview

Invitations allow you to invite someone to sign up to your application, via email. https://clerk.com/docs/authentication/invitations

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",
        "notify": True,
        "ignore_existing": True,
        "expires_in_days": 486589,
        "template_slug": clerk_backend_api.TemplateSlug.WAITLIST_INVITATION,
    })

    assert res is not None

    # 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(limit=20, offset=10, status=clerk_backend_api.ListInvitationsQueryParamStatus.PENDING, query="<value>")

    assert res is not None

    # Handle response
    print(res)

Parameters

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
status Optional[models.ListInvitationsQueryParamStatus] ➖ Filter invitations based on their status pending
query Optional[str] ➖ Filter invitations based on their email_address or id
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 */*

create_bulk_invitations

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.

Example Usage

from clerk_backend_api import Clerk

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

    res = clerk.invitations.create_bulk_invitations(request=[
        {
            "email_address": "[email protected]",
            "public_metadata": {
                "key": "<value>",
            },
            "redirect_url": "https://dreary-advancement.net/",
            "notify": True,
            "ignore_existing": False,
            "expires_in_days": 123536,
        },
        {
            "email_address": "[email protected]",
            "public_metadata": {
                "key": "<value>",
            },
            "redirect_url": "https://shrill-jet.net/",
            "notify": True,
            "ignore_existing": False,
            "expires_in_days": 665767,
        },
    ])

    assert res is not None

    # 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")

    assert res is not None

    # 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 */*