OAuth

Smatchly provides OAuth endpoints, so you can securely connect your application to smatchly.

Prerequisites

In order to integrate with smatchly via OAuth, you have to have a client_id. If you're not yet registered as an OAuth Partner, send an email to [email protected] containing:

• The name of the application you are trying to connect

• The URL we should redirect users to after a successful authorization (the redirect_uri). You can also supply multiple redirect_uri's.

Asking your Users for Authorization

Whenever you need your users to authorize in your application flow (for example after clicking a "connect with smatchly" button), you should redirect your users to the following domain:

https://app.smatchly.com/oauth/authorize?client_id=<client-id>&scope=<scopes-whitespace-separated>&redirect_uri=<redirect-uri>&response_type=code&state=<state>

client_id should be filled with the client-id that you received when registering as an OAuth-Partner at smatchly.

The value of scope should be one of (separated by whitespace):

• count-matching-contacts

You also have to specify a redirect_uri. This is where smatchly will redirect your users after a successful authorization. Please use the full URL, including https://. Example: https://your-app.com/oauth-smatchly-callback

The value of response_type should always be code.

state is a random string provided by you, which we will send back to you with the redirection to your redirect_uri. Use this to verify that you actually sent this authorization request to smatchly. This prevents malicious actors from calling your redirect_uri directly without you triggering an authorization request at smatchly.

Handling callbacks on your redirect_uri

If the user approves the authorization request, they will be redirected back to your application. You should first verify the state parameter against the value that was stored prior to the redirect. If the state parameter matches then you should issue a POST request to smatchly to request an access token. The request should include the authorization code that was issued by smatchly when the user approved the authorization request:

on('get', '/oauth/callback', function(request) {

    const state = request.session.state
    if(!state || state !== request.query.state) {
        throw new Error('Invalid state value.')
    }
    
    const repsonse = fetch('https://api.smatchly.com/v1/oauth/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'Accept': 'application/json'
        }
        body: JSON.stringify({
            grant_type: 'authorization_code',
            client_id: 'client-id',
            client_secret: 'client-secret',
            redirect_uri: 'http://your-app.com/oauth/callback',
            code: request.query.code,
        })
    })

});

This endpoint will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires. You can now use the access_token like it is described in Authentication

Refreshing Access Tokens

Since the access tokens issued by smatchly expire after one year, you will need to refresh your access token using the refresh_token that was provided to you when the access token was issued:

const repsonse = fetch('https://api.smatchly.com/v1/oauth/token', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
        'Accept': 'application/json'
    }
    body: JSON.stringify({
        grant_type: 'refresh_token',
        refresh_token: 'the-refresh-token'
        client_id: 'client-id',
        client_secret: 'client-secret',
        scope: '',
    })
})

This endpoint will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.