Integration guide

Before you begin

Check out the demo registration site using the login and registration flows documented below. You can see the demo here and view the source code here.

In the following sections you will need to know your XPKit base domain and Account ID.

See connecting to your instance of XPKit to determine your base domain.

If you are unsure what your Account ID is you can find this out by:

Logging into XPKit Portal
Clicking on your avatar
Your Account ID will be listed on this page

Wherever you see the {% base_domain %} and {% acccount_id %} tags substitute them with these values.

Notes on generating required OAuth parameters

In the following sections you will see the following parameters referenced in URLs.

client_id - you can find this value in XPKit Portal if you followed the instructions to create an OAuth application
state, code_challenge, code_verifier and code_challenge_method - see this guide for instructions on how to generate these values. The two challenge methods accepted by XPKit are plain and S256 (SHA256)
redirect_uri - you should provide a URI where the Auth API should redirect the user after a sign in attempt. Either a code and state or error and error_description will be returned to this address as GET parameters

To send a user into the login flow, add a Sign in with... button to your site with a URL pointing to:

https://auth.{% base_domain %}/authorize/
?response_type=code&provider=XXX
&client_id=XXX&state=XXX&code_challenge=XXX
&code_challenge_method=XXX&redirect_uri=XXX

See the list of available providers below to determine the value you should use for the provider param.

Available authentication providers

Provider name	URL param	Button downloads
Apple	apple	Link
Facebook	facebook	Link
Google	google	Link
LinkedIn	linkedin_oauth2	Link
Microsoft	microsoft	Link
XPKit	xpkit	Link

Register flow

If you are using XPKit as an authentication provider, a registration flow is provided. To send a user into this flow, add a Register with XPKit button to your site like so...

...with a URL pointing to:

https://auth.{% base_domain %}/registration/{% account_id %}/?redirect_uri=XXX

Note: if your account has been set to invite only, a code (?invite_code=XXX) is required on the button URL. Invites are usually sent out by account admins via XPKit Portal. Invite emails are sent to the invitees with URLs containing the required codes.

Redirect URIs

If the redirect_uri is missing in the sign in request, and there is only one specified in the OAuth app's redirect_uris field, that value will be used. If there is more than one specified, the first one will be used.

Handling errors

In the case of an error during the login flow the user will be redirected to the redirect_uri with error and error_description parameters. Here is a list of the errors you could expect to receive:

Error	Error description	More details
invalid_request	Mismatching redirect URI	The redirect_uri is not in the redirect_uris field.
invalid_request	Invalid redirect URI	The redirect_uri is not in the redirect_uris field and is an invalid URI.
invalid_request		The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client		The client is not authorized to request an authorization code using this method.
access_denied		The resource owner or authorization server denied the request.
server_error		The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
temporarily_unavailable		The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. Returned when the your XPKit license has expired.

Exchanging an authorization code for an access token

If an authorization code was successfully generated two parameters will be returned on the redirect URI:

code - the authorization code
state - the value received from the client returned back. The parameter should be used for preventing cross-site request forgery.

Once your app receives the code parameter on the redirect URI, it should attempt to exchange this code for an access token. The endpoint the POST request should be made to is:

https://auth.{% base_domain %}/api/token/

Example request (Python)

import requests

# Example using the EMEA region
token_exchange_endpoint = 'https://auth.emea.xpkit.net/api/token/'
data = {
    'grant_type': 'authorization_code',
    'code': 'available as the code param on the redirect URI',
    'client_id': 'available from XPKit Portal',
    'redirect_uri': 'same value as provided on sign in button',
    'code_verifier': 'see notes section above for guide'}

    # When you created the OAuth 2 app in XPKit Portal if you selected
    # "Confidential" as the client type the client secret is required...
    data['client_secret'] = 'available from XPKit Portal'

req = requests.post(token_exchange_endpoint, data=data)
content = req.json()

access_token = content['access_token']
scopes = content['scope']
expires = content['expires_in']

Errors exchanging a code for a token

If there was a problem exchanging an authorization code for an access token, here is a list of the errors you could expect to receive:

Error	Error description	More details
invalid_request	Mismatching redirect URI	The redirect_uri is not in the redirect_uris field.
invalid_request	Invalid redirect URI	The redirect_uri is not in the redirect_uris field and is an invalid URI.
invalid_client		The client_id or client_secret is not valid.
invalid_grant		The code_verifier or code is not valid.
unsupported_grant_type		The grant_type is not valid