Our OAuth2 authentication method will allow you to interactively request that a user authorise your application to act on behalf of their account. You'll receive a token that you can use to act on behalf of the user.
OAuth2 is an industry standard authorization protocol. The Cohort Go platform supports the "Authorization Code" flow, issuing a token that can be used to act on behalf of a user.
Before you start, you'll need to contact your account representative at Cohort Go to have your OAuth application registered. They will provide you with a Client ID and Secret to use through the rest of this process.
To begin an authorization request, you'll need to construct a URL for your user to click that starts the authorisation process. For example, if you have a client ID of 'some-test-app' and your application will receive the returned code at https://example.org/oauth2/code, then you'd create a link like:
<a href="https://portal.cohortgo.com/oauth2/authorize?client_id=some-test-app&redirect_uri=https://example.org/oauth2/code&response_type=code">Connect your Cohort Go Account</a>
This will redirect the user to their login page on the Cohort Go portal. After they login, they'll be asked to approve access to the application.
Upon approval, the Cohort Go Portal will redirect the uer back to your redirect_uri, including a code parameter. Take this code, and POST it to https://portal.cohortgo.com/oauth2/token, including the following parameters:
client_id - your client ID, eg, some-test-app;grant_type - should be fixed as authorization_code;mode - should be fixed as server;code - the code that you received via the code parameter;client_secret - the Client Secret provided by Cohort Go when we enabled your OAuth2 access;A successful response from Cohort Go will return a JSON payload like:
{
access_token: "Some Token",
token_type: 'bearer',
scope: "",
api_base_url: "https://portal.cohortgo.com/api/v1",
base_url: "https://portal.cohortgo.com"
}
The access_token should be safely stored - this is your credential to access the customer's account. The api_base_url should be used for any future API requests. Note that this may vary on a per-customer basis depending upon their account configuration with Cohort Go.
To make a request to the Cohort Go API using OAuth2, use the API base URL returned to construct the URL, and include an Authorization: Bearer <access_token> header.
In case of an advanced integration, you may want your application to be able to act on behalf of multiple users. For example, if you have a CRM platform that wants to offer streamlined booking of payments, you'll want to record the original user against the payment to ensure that notifications are sent to appropriate users.
To enable this functionality, include scope=act-as-user when building your authorization URL. So your full URL might look like:
<a href="https://portal.cohortgo.com/oauth2/authorize?client_id=some-test-app&redirect_uri=https://example.org/oauth2/code&response_type=code&scope=act-as-user">Connect your Cohort Go Account</a>
When approving this request, the user will be notified that this gives your application access to act as any user within their account.
Upon successful approval, you'll receive a code as per the normal flow, and should exchange it with the token endpoint. This token will not be issued to the currently logged in user however - it will be issued against an automatically generated "system user" within the account.
When making a request, alongside the Authorization: Bearer <access_token> header, also include a X-Act-as-User header with the name and email address of the user that you want to act on behalf of. If this user exists within the target account, then the operation will be executed as that user.
For example, include a header like X-Act-as-User: "Bob Smith" <[email protected]> to act as the user user Bob Smith.
We provide two options for dealing with users that don't yet exist in the Cohort Go Platform.
Firstly, you can use our Users API to create users before you require them. We recommend that you store a flag in your system as to whether you've already provisioned a user to reduce API calls and improve your user flow.
Alternatively, you can include the auto-create-users entry into your requested scope (eg, &scope=act-as-user,auto-create-users). If you present an email address that does not match a known user, the Cohort Go platform will automatically create a new user with access permissions to the default branch in your account and a 'None' role (which gives them the ability to receive notifications, but not interactively login). The name and email provided as part of the request will be used to initialize this user. If you later wish to "upgrade" this user to one that can login, this can be done via the Portal UI.