OAuth2 Clients

OAuth2 clients let your application interact with your organization's Guru workspace through the API on behalf of your users.

To enable OAuth2 clients for your workspace, email [email protected].

Client maintenance endpoints

Create an OAuth2 client

POST /api/v1/oauthclients

For scopes, use default or *:* for read/write access, or read:* for read-only. The bottomDescription field holds additional descriptive text that appears at the bottom of the authorization screen.

Request

{
  "name": "My Client",
  "description": "Allows XYZ Co to perform actions on your behalf",
  "bottomDescription": "",
  "redirectUris": ["https://example.com/callback"],
  "scopes": ["read:*"]
}

Response

The response includes a clientId and clientSecret. You need both for the client maintenance endpoints and for the OAuth2 authorization flow itself.

{
  "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, get, and update clients

GET /api/v1/oauthclients returns an array of your clients, each in the same shape as the create response. GET /api/v1/oauthclients/{clientId} returns a single client.

To update a client, send the same fields as the create request:

PUT /api/v1/oauthclients/{clientId}

The response matches the create response.

Update the client logo

Upload an image as multipart form data with the key logo:

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

Delete a client

DELETE /api/v1/oauthclients/{clientId}

Authorization flow

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

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 request, they are redirected to your redirect_uri with two query parameters:

• state: the same state parameter you passed in, if any.
• code: an authorization code to exchange for an access token.

Token exchange (authorization code)

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
}

The access token expires after an hour. To get a new one, exchange the refresh token as shown below.

Token exchange (refresh token)

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
}

The new access token also expires after an hour; exchange the refresh token again when it does.

For a worked example of wiring an OAuth2 client into a real integration, see OAuth2 Example: Custom GPT.