Skip to content

Latest commit

 

History

History
141 lines (97 loc) · 20.8 KB

README.md

File metadata and controls

141 lines (97 loc) · 20.8 KB
Raw

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 - Create an invitation
  • list - List all invitations
  • revoke - Revokes an invitation

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

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.invitations.create(email_address="user@example.com", public_metadata={

    }, redirect_url="https://example.com/welcome", notify=True, ignore_existing=True, expires_in_days=486589)

    if res is not None:
        # handle response
        pass

Parameters

Parameter Type Required Description Example
email_address str ✔️ The email address the invitation will be sent to user@example.com
public_metadata Dict[str, Any] ➖ Metadata that will be attached to the newly created invitation.
The value of this property should be a well-formed JSON object.
Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.		 {}
redirect_url Optional[str] ➖ Optional URL which specifies where to redirect the user once they click the invitation link.
This is only required if you have implemented a custom flow and you're not using Clerk Hosted Pages or Clerk Components.		 https://example.com/welcome
notify OptionalNullable[bool] ➖ Optional flag which denotes whether an email invitation should be sent to the given email address.
Defaults to true.		 true
ignore_existing OptionalNullable[bool] ➖ Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user. ​false
expires_in_days OptionalNullable[int] ➖ The number of days the invitation will be valid for. By default, the invitation does not expire.
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 s:
    res = s.invitations.list(limit=20, offset=10, status=clerk_backend_api.ListInvitationsQueryParamStatus.PENDING)

    if res is not None:
        # handle response
        pass

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

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 s:
    res = s.invitations.revoke(invitation_id="inv_123")

    if res is not None:
        # handle response
        pass

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