UserKit API Reference

Create or update a user

POST: /v1/users
POST: /v1/users/<user_id>

Get a user by id, or list users

GET: /v1/users
GET: /v1/users/<user_id>

Login a user

POST: /v1/users/login
:param username:
    Username of user trying to login
:param password:
    Password of user trying to login
:param login_code:
    Optional n-factor code sent out via the send_nfactor_code endpoint.
    If user has 2-factor auth turned on, this will be required, and
    an error will be returned indicating that a two-factor code must
    be requested/entered.
:returns:
    Returns a UserToken if login succeeds.

Login a Google SignIn user

POST: /v1/users/login/google
:param google_id_token:
    The Google user id-token from successful Google SignIn.
:returns:
    Returns a UserToken if login succeeds.

Logout a user

POST: /v1/users/logout

Get a logged in user

GET: /v1/users/by_token
Get a user by their session-token.

:param user_token:
    The UserToken representing the user.
:returns:
    A user object if user_token is valid, otherwise returns null.

Refresh a stale user-session token

GET: /v1/users/auth_token
Use an existing auth token to fetch a new one. This endpoint
can be used to "refresh" a token before it expires (e.g. once
a day). This causes a new token to be generated, while the old
token remains valid for a grace-period of a few minutes.

App can send this in the X-User-Token header like this:

    X-User-Token: <token>

Request a password-reset for a user

POST: /v1/users/request_password_reset

Set a new password with reset-token

POST: /v1/users/password_reset_new_password
This endpoint accepts the password-reset token the user
received via email or SMS, along with their new password.

Set a user's disabled state

POST: /v1/users/<user_id>/disable
Disabled users can no longer login.

Expects a JSON body:

    {
        "disabled": <Boolean>
    }

:param user_id:
    User ID for the user being updated.

:param disabled:
    The disable state

:returns:
    <user> if it succeeds, otherwise returns a JSON error.

Set a user's auth type

POST: /v1/users/<user_id>/auth_type
Update the auth_type, Requires a phone verification success token in
order to set auth_type to two-factor or OTP. Use the verify-phone
endpoint to verify a phone and receive a phone-verified-success token.

Expects a JSON body:

    {
        "auth_type": <string>,
        "phone": <string> OR null,
        "verified_phone_token": <string> OR null,
        "google_id_token": <string> OR null,
        "password": <string> OR null
    }

:param user_id:
    User ID for the user being updated.

:param auth_type:
    The new auth type ("two_factor", "otp" or "password").
:param phone:
    The phone number to which login codes will be sent if auth_type is
    being set to OTP or 2FA. Otherwise None.
:param verified_phone_token:
    The verified_success_token for the phone to which login codes
    will be sent if auth_type  is being set to OTP or 2FA, otherwise
    None. This token can be retrieved via the verify_phone endpoint.
:param google_id_token:
    The google-id-token retrieved by the user during Google SignIn.
    We need this so we can verify and associate the Google account
    with this UserKit user.
:param password:
    The password to use for an `auth_type` that requires one.

:returns:
    {"success": True} if it succeeds, otherwise returns a JSON error.

Send a phone-verification code

POST: /v1/users/request_phone_verification_code
Handles sending out a verification code to a phone number via
SMS or call.

phone:
    The phone number to which verification code should be sent.
send_method:
    The method by which code should be sent ("sms" or "call").

return:
    {"success": true} if code was sent, otherwise returns an
    an error.

Send an email verification code

POST: /v1/users/request_email_verification_code
Sends an email verification link which user can click to verify
they own that email address.

email:
    The email address to which verification link will be sent.

returns:
    {"success": true} if email was sent.

Check a phone-verification code

POST: /v1/users/verify_phone
Checks that a verification code is correct for the phone number

phone:
    Phone number to be verified.
code:
    Verification code that was sent to the phone (via
    RequestChannelVerificationCode endpoint).


returns:
    { // JSON
        'verified': Boolean,
        'verified_phone_token': String  // Null if 'verified' is False
    }

    'verified':
        True if code is correct, otherwise False.
    'verified_phone_token':
        Contains a secret token if verification is
        successful, otherwise null. The token can be passed into the
        user-create endpoint to add this number as the
        user.verified_phone. This allows us to validate a phone before
        creating a user during user signup.

Check email-verification code

POST: /v1/users/verify_email
Checks that a verification code is correct for the email address.

email:
    Email address to be verified.
code:
    Verification code that was sent to the email (via
    RequestChannelVerificationCode endpoint).


returns:
    { // JSON
        'verified': Boolean,
        'verified_email_token': String  // Null if 'verified' is False
    }

    'verified':
        True if code is correct, otherwise False.
    'verified_email_token':
        Contains a secret token if verification is successful,
        otherwise null. The token can be passed into the user-create
        endpoint to add this email as the user.verified_email. This
        allows us to validate an email before creating a user during
        user signup.

Check phone-verification code and add phone to user

POST: /v1/users/<user_id>/verify_phone_for_user
Checks that a verification code is correct for the phone, and sets
user.verified_phone to the phone number.

phone:
    Phone number to be verified.
code:
    Verification code that was sent to the phone (via
    RequestChannelVerificationCode endpoint).

returns:
    { // JSON
        'verified': Boolean
    }

    'verified':
        True if phone was verified successfully, in which case
        user.verified_phone will have been set to the phone number.
        Otherwise False.

Check email-verification code and add email to user

POST: /v1/users/<user_id>/verify_email_for_user
Checks that a verification code is correct for the email, and sets
user.verified_email to the email address.

email:
    Email address to be verified.
code:
    Verification code that was sent to the email (via
    RequestPhoneVerificationCode endpoint).

returns:
    { // JSON
        'verified': Boolean
    }

    'verified':
        True if email was verified successfully, in which case
        user.verified_email will have been set to the email address.
        Otherwise False.

Create an invite

POST: /v1/invites
This endpoint creates, but does not send, an invite.

Accepts JSON like this:

    {
        // Required
        "to_email": "jill@example.com",

        // Optional
        "expires_secs": 86400,
        "from_user": "usr_jG3aFsdf8igjSd",
        "extras": {
            "permissions": ["edit", "view"]
        }
    }

Returns a JSON object like this:

    {
        // ... usual invite properties, plus:
        "token_raw": "invt_ax1-AbID8gj0Lpga"
        "invite_url": "https://example.com/a?invt=invt_aX1-..",
    }

to_email:
    Invited email, required.
expires_secs:
    Optional, how many seconds before this invite expires.
extras:
    Optional JSON object with extra properties to be stored in
    the Invite entity. For example if inviting someone to a
    join an admin team for an app, you could add the
    permissions being granted, and when the invite is accepted,
    you could grant those permissions to the invited user.

returns:
    The created invite as JSON if it succeeds, or a JSON error
    object if it fails. Includes a token_raw property that is
    only available

Get an invite by id, or list invites

GET: /v1/invites
GET: /v1/invites/<invite_id>

Accept an invite

POST: /v1/invites/accept
Takes a JSON object like this:

    {
        "user_id": "usr_lIS8ghhaV9k0i",
        "token": "invt_abc123-hij567"
    }

URL Params:
    user_id: The user who's accepting this invite.
    token: Token string for the invite being accepted.

Get an invite by token

GET: /v1/invites/by_token
Expects a header like this:

    "X-Invite-Token: <INVITE_TOKEN>"

Returns an invite object if the token is valid.
If token is not valid returns a resource-not-found error
object.

Get an invite by token once. Not-found-error subsequently

GET: /v1/invites/get_once
Expects a header like this:

    "X-Invite-Token: <INVITE_TOKEN>"

Returns an invite object if the token is valid and not fetched
previously. If token is not valid or was already fetched via
this endpoint previously, it returns a resource-not-found error
object instead.

Create and send an invite link via email

POST: /v1/invites/send
Accepts a JSON body like this:

    {
        // Required
        "to_email": "jill@example.com",    // Invited email

        // Optional
        "expires_secs": 86400,
        "from_user": "usr_jG3aFsdf8igjSd",
        "greeting": "Hi there!",
        "body": "You're invited to join Example App.",
        "signature": "Thanks! - The Example Team",
        "extras": {
            // Example custom property:
            "permissions": ["edit", "view"]
        }
    }

An invite email is sent to `email` containing the `greeting`,
`body` and `signature` text, plus the invite invite link.

to_email:
    Invited email, required.
expires_secs:
    Optional, how many seconds before this invite expires.
greeting:
    Optional, greeting part of invite email, ie. "Hi there!"
body:
    Optional, main part of invite email, ie. "You're invited to
    our cool app."
signature:
    Optional, signature part of invite email, ie. "Thanks!


    The Cool App team".
extras:
    Optional JSON object with extra properties to be stored in
    the Invite entity. For example if inviting someone to a
    join an admin team for an app, you could add the
    permissions being granted, and when the invite is accepted,
    you could grant those permissions to the invited user.

returns:
    The created invite as JSON if it succeeds, or a JSON error
    object if it fails.

Create a custom audit-log event

POST: /v1/audits
Accepts JSON like this:

    {
        // Required
        'actor': '{user-id in your app}'
        'actor_ip': '{IP address of the original actor}'
        'actor_useragent': '{User-Agent of the original actor}'

        'action': '{String identifier for action i.e. "user.created" }'

        // Optional
        'actee': '{user-id in your app}'
        'details': '{extra string data describing action}'
    }

Returns a JSON object like this:

    {
        'id': '<audit-id>'
        'action': '<action passed to endpoint>',
        'details': '<details passed to endpoint>',

        'request': { Request Object }
        'request_ip': '<request ip address>',

        'actor': '<user making the logging request>',
        'actor_app': '<app-id of the app the user belongs to>',
        'actor_session': '<session-id for the current user>',
        'actor_ip': '<ip address of the current user>',
        'actor_useragent': '<user-agent of the current user>',
        'actor_location': '<current user location>',

        'actee': '<actee identifier passed to the endpoint>',
        'actee_app': '<app the actee belongs to>',

        'occurred': '<time of the event logging>'
    }

returns:
    The created audit log event as JSON if it succeeds, or a JSON error
    object if it fails.

None

GET: /v1/audits
GET: /v1/audits/<audit_id>

None

GET: /v1/audits/user/<user_id>

Get a pending-email by it's encryption key

GET: /v1/emails/pending
Expects a header like this:

    X-Email-Key: <email_key>

Returns decrypted email JSON like this:

    {
        "id": "eml_MgXuRwRr0hIXf8",
        "to": "jane.smith@example.com",
        "subject": "Reset your password",
        "body": "Click here: https://example.com/a?pwrs=a3-hI2"
    }

Proxy endpoint for developers to make widget requests

POST: /v1/widget/proxy
Accepts a JSON body like this:

    {
        "token_private": "j9FHlc3fJl0dVM",
        "data": {
            "token": "j9FHlc3fJl0dVM",
            "endpoint": "login",
            "method": "post",
            "payload": <json_object>
        },
        "ip": "127.0.0.1", // Optional
    }

private_token:
    User's private token. Can be null for requests which don't
    require it (such as login).
data:
    The JSON data intended for a widget endpoint. Includes
    extra info like which widget endpoint is the target.

returns:
    JSON object like this:

        {
            "token_private": "j9FHlc3fJl0dVM",
            "response": {
                "status_int": 200,
                "data": <json_object>
            }
        }

None

GET: /v1/widget/settings

Login a user

POST: /v1/widget/login
:param username:
    Username of user trying to login
:param password:
    Password of user trying to login
:recaptcha_response:
    Optional recaptcha code.
:param login_code:
    Optional n-factor code sent out via the send_nfactor_code endpoint.
    If user has 2-factor auth turned on, this will be required, and
    an error will be returned indicating that a two-factor code must
    be requested/entered.
:returns:
    Returns a UserToken if login succeeds.

Login a user

POST: /v1/widget/login/google
:param google_id_token:
    The Google user id-token from successful Google SignIn.
:returns:
    Returns a UserToken if login succeeds.

Logout a user

POST: /v1/widget/logout

Get a user's login auth_type

POST: /v1/widget/login_info
This endpoint allows the login widget to send the user identifier
(username, email...) and find out what auth_type this user has enabled
such as "password", "two-factor", etc.

Takes a JSON body:

    {"identifier": <string>}

Returns:

    {"auth_type": <string>}

Send a login-code (for 2FA or OTP)

POST: /v1/widget/send_login_code
Send out a code via the selected send_method (e.g. 'sms' or 'call').

:param username:
    The user identifier (username or email) of the user who is
    attempting to sign in.
:param password:
    The raw password of the user who is attempting to sign in.
:param send_method:
    The send_method (e.g. 'sms' or 'call') for how code will be sent.

The code will only be sent out if the username and password are
correct.

Refresh a stale user-session token

GET: /v1/widget/auth_token
Use an existing auth token to fetch a new one. This endpoint
can be used to "refresh" a token before it expires (e.g. once
a day).

App can send this in the X-User-Token header like this:

    X-User-Token: <token>

Register a new user

POST: /v1/widget/users
Creates the user, and a new session for that user.

Returns JSON like this:

    {
        "user": <user>,
        "session": {
            'token': <string>,
            'refresh_after_secs': <number>,
            'expires_in_secs': <number>
        }
    }

Request a password-reset for a user

POST: /v1/widget/request_password_reset

Set a new password with reset-token

POST: /v1/widget/password_reset_new_password
This endpoint accepts the password-reset token the user
received via email or SMS, along with their new password.

Check if a password-reset token is valid

POST: /v1/widget/password_reset_check_token
This endpoint accepts the password-reset token the user
received via email or SMS, and checks if it's currently valid
and hasn't expired.

Returns:

    {'valid': success}, where success is True if token is valid
    or False otherwise.

None

POST: /v1/widget/password_reset_send_2fa_code

Update user settings

POST: /v1/widget/user_settings

Get user settings

GET: /v1/widget/user_settings

Set user's auth-type (2FA, password, etc.)

POST: /v1/widget/user_auth_type
Update the auth_type, requires a phone verification success token in
order to set auth_type to two-factor or OTP. Use the verify-phone
endpoint to verify a phone and receive a phone-verified-success token.

Expects a JSON body:

    {
        "auth_type": <string>,
        "phone": <string> OR null,
        "verified_phone_token": <string> OR null,
        "google_id_token": <string> OR null,
        "password": <string> OR null,
    }

:param auth_type:
    The new login type
:param phone:
    The phone number to which login codes will be sent if auth_type is
    being set to OTP or 2FA. Otherwise None.
:param verified_phone_token:
    The verified_success_token for the phone to which login codes
    will be sent if auth_type  is being set to OTP or 2FA, otherwise
    None.
:param google_id_token:
    The google-id-token retrieved by the user during Google SignIn.
    We need this so we can verify and associate the Google account
    with this UserKit user.
:param password:
    The password to use for an `auth_type` that requires one.

:returns:
    {"success": True} if it succeeds, otherwise returns a JSON error.

Change password

POST: /v1/widget/change_password
password:
    The current password.
new_password:
    The new password.

returns:
    {"success": true} if it succeeded, or a JSON error.

Send a phone-verification code

POST: /v1/widget/request_phone_verification_code
Handles sending out a verification code to a phone number via
SMS or call.

phone:
    The phone number to which verification code should be sent.
send_method:
    The method by which code should be sent ("sms" or "call").

return:
    {"success": true} if code was sent, otherwise returns an
    an error.

Send an email verification code

POST: /v1/widget/request_email_verification_code
Sends an email verification link which user can click to verify
they own that email address.

email:
    The email address to which verification link will be sent.

returns:
    {"success": true} if email was sent.

Check a phone-verification code

POST: /v1/widget/verify_phone
Checks that a verification code is correct for the phone number

phone:
    Phone number to be verified.
code:
    Verification code that was sent to the phone (via
    RequestChannelVerificationCode endpoint).


returns:
    { // JSON
        'verified': Boolean,
        'verified_phone_token': String  // Null if 'verified' is False
    }

    'verified':
        True if code is correct, otherwise False.
    'verified_phone_token':
        Contains a secret token if verification is
        successful, otherwise null. The token can be passed into the
        user-create endpoint to add this number as the
        user.verified_phone. This allows us to validate a phone before
        creating a user during user signup.

Check email-verification code

POST: /v1/widget/verify_email
Checks that a verification code is correct for the email address.

email:
    Email address to be verified.
code:
    Verification code that was sent to the email (via
    RequestChannelVerificationCode endpoint).


returns:
    { // JSON
        'verified': Boolean,
        'verified_email_token': String  // Null if 'verified' is False
    }

    'verified':
        True if code is correct, otherwise False.
    'verified_email_token':
        Contains a secret token if verification is successful,
        otherwise null. The token can be passed into the user-create
        endpoint to add this email as the user.verified_email. This
        allows us to validate an email before creating a user during
        user signup.

Check phone-verification code and add phone to user

POST: /v1/widget/verify_phone_for_user
Checks that a verification code is correct for the phone, and sets
user.verified_phone to the phone number.

phone:
    Phone number to be verified.
code:
    Verification code that was sent to the phone (via
    RequestChannelVerificationCode endpoint).

returns:
    { // JSON
        'verified': Boolean
    }

    'verified':
        True if phone was verified successfully, in which case
        user.verified_phone will have been set to the phone number.
        Otherwise False.

Check email-verification code and add email to user

POST: /v1/widget/verify_email_for_user
Checks that a verification code is correct for the email, and sets
user.verified_email to the email address.

email:
    Email address to be verified.
code:
    Verification code that was sent to the email (via
    RequestPhoneVerificationCode endpoint).

returns:
    { // JSON
        'verified': Boolean
    }

    'verified':
        True if email was verified successfully, in which case
        user.verified_email will have been set to the email address.
        Otherwise False.

Accept an invite

POST: /v1/widget/invites/accept
Accept an invite on behalf of a user.

token:
    The invite token.
returns:
    Returns {"success": true} if invite was accepted
    successfully, otherwise returns a JSON error.

None

GET: /cron/delete_old_backups