Cloverleaf

How to Create a Cloverleaf Integration as a Developer

Contact the Cloverleaf engineer team at <a href="mailto:support@cloverleaf.me" target="_blank" rel="nofollow noopener noreferrer">support@cloverleaf.me</a> and tell us you’re creating a Cloverleaf Integration.

1. integration name
2. description
3. square logo image (ideally 80x80 px or larger)
4. integration documentation URL OR company URL
5. support URL OR email address
6. best point of contact’s email address for this integration, which might be yours
    

In return, we will issue you a client ID and secret. We use the <a href="https://openid.net/specs/openid-connect-basic-1_0.html" target="_blank" rel="nofollow noopener noreferrer">OpenID Connect</a> (OIDC) protocol for authentication and these pertain to it.

Now that you have the client ID and secret, you can integrate using OIDC. The flow is:

GET https://app.cloverleaf.me/api/oidc/auth with parameters: response_type=code scope=openid client_id=&lt;your client ID&gt; redirect_uri=&lt;integration's callback URL&gt; state=&lt;unique, ideally random state value&gt;

Note the <code>redirect_uri</code> above. This is your integration’s callback URL for receiving, via URL parameters, the authorization code.

A <code>303 Redirect</code> response will come back, sending the user to:

1. sign into Cloverleaf if not already
2. then the SSO Consent page, where they click Authorize to allow the integration access to Cloverleaf
    

Once Authorized, your <code>redirect_uri</code> will be hit with a <code>GET</code> request, with the following URL params:

1. <code>code</code> the authorization code your integration will use to exchange for an access token
2. <code>iss</code> the auth code issuer, which is Cloverleaf
3. <code>state</code> the unique state value your integration initially provided, for verification

Once the auth code is obtained, it’s time to exchange it for the access token that lets the integration use Cloverleaf

Your integration will make a POST request:

POST https://app.cloverleaf.me/api/oidc/token with x-www-form-urlencoded parameters: client_id: &lt;your client ID&gt; client_secret: &lt;your client secret&gt; grant_type: authorization_code code: &lt;auth code given in Step 7&gt; redirect_uri: &lt;integration's callback URL&gt;

An <code>access_token</code> will be returned, allowing the integration access to Cloverleaf on behalf of the user.

Provide this <code>access_token</code> in the <code>authorization</code> header as a bearer token when calling the Cloverleaf Public API endpoint:

1. Contact the Cloverleaf engineer team at <a href="mailto:support@cloverleaf.me" target="_blank" rel="nofollow noopener noreferrer">support@cloverleaf.me</a> and tell us you’re creating a Cloverleaf Integration.
 
2. Provide us the following information:
 1. integration name
 2. description
 3. square logo image (ideally 80x80 px or larger)
 4. integration documentation URL OR company URL
 5. support URL OR email address
 6. best point of contact’s email address for this integration, which might be yours
 
3. In return, we will issue you a client ID and secret. We use the <a href="https://openid.net/specs/openid-connect-basic-1_0.html" target="_blank" rel="nofollow noopener noreferrer">OpenID Connect</a> (OIDC) protocol for authentication and these pertain to it.
 
4. Now that you have the client ID and secret, you can integrate using OIDC. The flow is:
 
 GET https://app.cloverleaf.me/api/oidc/auth with parameters: response_type=code scope=openid client_id=&lt;your client ID&gt; redirect_uri=&lt;integration's callback URL&gt; state=&lt;unique, ideally random state value&gt;
 
 
5. Note the <code>redirect_uri</code> above. This is your integration’s callback URL for receiving, via URL parameters, the authorization code.
 
6. A <code>303 Redirect</code> response will come back, sending the user to:
 1. sign into Cloverleaf if not already
 2. then the SSO Consent page, where they click Authorize to allow the integration access to Cloverleaf
 
7. Once Authorized, your <code>redirect_uri</code> will be hit with a <code>GET</code> request, with the following URL params:
 1. <code>code</code> the authorization code your integration will use to exchange for an access token
 2. <code>iss</code> the auth code issuer, which is Cloverleaf
 3. <code>state</code> the unique state value your integration initially provided, for verification
 
8. Once the auth code is obtained, it’s time to exchange it for the access token that lets the integration use Cloverleaf
 
9. Your integration will make a POST request:
 POST https://app.cloverleaf.me/api/oidc/token with x-www-form-urlencoded parameters: client_id: &lt;your client ID&gt; client_secret: &lt;your client secret&gt; grant_type: authorization_code code: &lt;auth code given in Step 7&gt; redirect_uri: &lt;integration's callback URL&gt;
 
10. An <code>access_token</code> will be returned, allowing the integration access to Cloverleaf on behalf of the user.
 
11. Provide this <code>access_token</code> in the <code>authorization</code> header as a bearer token when calling the Cloverleaf Public API endpoint:

GET https://app.cloverleaf.me/public-api/v1/self/daily-coaching

A step by step guide for developers who are interested in building an integration to the Cloverleaf Platform.