OAuth2 Clients can be used for the purpose of interacting with your organization's Guru instance through the API on behalf of your users.

To start using OAuth2 Clients, please email our Support Team today at [email protected].

OAuth2 Client Maintenance APIs

Create an OAuth2 Client

POST /api/v1/oauthclients

Request Body

Scopes:

default or *:* - read/write
read:* - read only

{
  "name": "My Client",
  "description": "Allows XYZ Co to perform actions on your behalf",
  "bottomDescription": "", //more descriptive text which appears at the bottom of the Authorization screen
  "redirectUris": ["https://example.com/callback"],
  "scopes": ["read:*"]
}

Response

The response will include a clientId and clientSecret for the new client. These are essential pieces of information for using the OAuth2 Client Maintenance APIs along with as part of the actual OAuth2 authorization flow.

{
  "clientId" : "824a71ef-bcd0-4931-862e-ecf059220d52",
  "clientSecret" : "e72c7a1c5e8f4833bed98ff65be077cc6843eb66752a496293a5d65a753d8d96",
  "redirectUris" : [ "https://example.com/callback" ],
  "scopes" : [ "read:*" ],
  "name" : "My Client",
  "description" : "Allows XYZ Co to perform actions on your behalf"
}

List OAuth2 Clients

GET /api/v1/oauthclients

Response

[ 
  {
    "clientId" : "824a71ef-bcd0-4931-862e-ecf059220d52",
    "clientSecret" : "e72c7a1c5e8f4833bed98ff65be077cc6843eb66752a496293a5d65a753d8d96",
    "redirectUris" : [ "https://example.com/callback" ],
    "scopes" : [ "read:*" ],
    "name" : "My Client",
    "description" : "Allows XYZ Co to perform actions on your behalf"
	} 
]

Get an OAuth2 Client

GET /api/v1/oauthclients/{clientId}

Response

{
  "clientId" : "824a71ef-bcd0-4931-862e-ecf059220d52",
  "clientSecret" : "e72c7a1c5e8f4833bed98ff65be077cc6843eb66752a496293a5d65a753d8d96",
  "redirectUris" : [ "https://example.com/callback" ],
  "scopes" : [ "read:*" ],
  "name" : "My Client",
  "description" : "Allows XYZ Co to perform actions on your behalf"
}

Update OAuth2 Client

PUT /api/v1/oauthclients/{clientId}

Request Body

{
  "name": "My Client",
  "description": "Allows XYZ Co to perform actions on your behalf",
  "bottomDescription": "", //more descriptive text which appears at the bottom of the Authorization screen
  "redirectUris": ["https://example.com/callback"],
  "scopes": ["read:*"]
}

Response

{
  "clientId" : "824a71ef-bcd0-4931-862e-ecf059220d52",
  "clientSecret" : "e72c7a1c5e8f4833bed98ff65be077cc6843eb66752a496293a5d65a753d8d96",
  "redirectUris" : [ "https://example.com/callback" ],
  "scopes" : [ "read:*" ],
  "name" : "My Client",
  "description" : "Allows XYZ Co to perform actions on your behalf"
}

Update OAuth2 Client Logo

This is a multipart form data upload of an image file. The image file should be uploaded with the key of logo

POST /api/v1/oauthclients/{clientId}/logoUrl

Delete OAuth2 Client

This will remove the OAuth2 client and revoke all authorizations associated with the client. This action is irreversible.

DELETE /api/v1/oauthclients/{clientId}

OAuth2 Usage APIs

Authorization

The authorization URL is https://api.getguru.com/oauth/authorize. To initiate the authorization flow, you will direct your users to the URL below:

https://api.getguru.com/oauth/authorize?client_id=<the client ID for your client>
&response_type=code
&redirect_uri=<one of the redirect URIs defined on the client>
&state=<any value you want returned to you at the end of the authorization flow>
&scope=<comma separated list of scopes>

After the user approves the authorization request, they will be redirected to the location of the redirect_uri in the authorization request and there will be two query parameters:

state - the same state parameter passed into the authorization URL (if any)
code - an authorization code used to exchange for an access token (see following section)

Token Exchange (from initial authorization code)

To initiate the token exchange flow, your integration should make a POST request to https://api.getguru.com/oauth/token:

https://api.getguru.com/oauth/token?client_id=<the client ID for your client>
&grant_type=authorization_code
&code=<>
&redirect_uri=<one of the redirect URIs defined on the client>
&scope=<the same scopes used in the authorization call>
&client_secret=<>

Response

{
  "token_type" : "bearer",
  "scope" : "<the scope passed in>",
  "access_token" : "<xxxxxxxxxxxxxxx>",
  "refresh_token" : "<**************>",
  "user_id" : "<email address of the user>",
  "expires_in" : 3599
}

It is important to note that the access token returned will expire after an hour. To get a new access token, the refresh token can be exchanged as indicated below.

Token Exchange (from refresh token)

To initiate the token exchange flow, your integration should make a POST request to https://api.getguru.com/oauth/token:

https://api.getguru.com/oauth/token?client_id=<the client ID for your client>
&grant_type=refresh_token
&refresh_token=<the refresh token from the original auth code exchange>
&client_secret=<>

Response

{
  "token_type" : "bearer",
  "scope" : "<the scope passed in>",
  "access_token" : "<xxxxxxxxxxxxxxx>",
  "user_id" : "<email address of the user>",
  "expires_in" : 3599
}

It is important to note that the access token returned will expire after an hour. To get a new access token, the refresh token can be exchanged again.