OAuth 2.0 authentication

Glue supports OAuth2 authentication, which is required in order to utilize the API. An OAuth2 authorization grant flow can be used to install an app to a workspace and to obtain an access token for a dedicated user associated with an app in the given workspace. For private apps, it's also possible for apps to be installed to a workspace from within the product.

Regardless of installation method, once an app is installed to a workspace, an OAuth2 token request with client credentials can also be used to obtain an access token for a given app user by providing a workspace ID. This can eliminate the burden of maintaining a single set of access and refresh tokens for each workspace that an app is installed to.

The app user tokens you obtain allow you to perform operations using a specific user associated with your app. In the future we plan to allow apps to obtain tokens for standard Glue users using an OAuth2 authorization grant flow.

You must create a workspace for the purpose of managing the OAuth2 Application.

Create an OAuth2 application

Create a new OAuth2 Application in Glue and configure the redirect callback URLs to your application.

If you're having trouble finding Custom Apps, contact [email protected] to ensure Custom OAuth Apps are enabled on your workspace!

Redirect user access requests to Glue

When authorizing a user to the Glue API, redirect to an authorization URL with correct parameters and scopes:

GET https:/api.gluegroups.com/oauth/authorize HTTP/1.1

Name	Description
client_id	(required) Client ID provided when you create the OAuth2 Application
redirect_uri	(required) Redirect URI
response_type=code	(required) Expected response type
scope	(required) Comma separated list of scopes.
state	(optional) Prevents CSRF attacks and should always be supplied. Read more about it here

Example

GET https://api.gluegroups.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URL&state=SECURE_RANDOM&scope=workspaces%3Aread HTTP/1.1

Handle the redirect URLs you specified in the OAuth2 Application

Once the user approves your application they will be redirected back to your application, with the OAuth authorization code in the URL params.

Any state parameter you specified in step 2 will also be returned in the URL params and must match the value specified in step 2. If the values do not match, the request should not be trusted.

Example

GET https://example.com/oauth/callback?code=9a5190f637d8b1ad0ca92ab3ec4c0d033ad6c862&state=b1ad0ca92 HTTP/1.1

Exchange code for an access token

After receiving the code, you can exchange it for a Glue API access token:

POST https://api.gluegroups.com/oauth/token HTTP/1.1

Pass parameters in body as URL-encoded form submission, where the Content-Type header must be application/x-www-form-urlencoded.

Parameter	Description
code	(required) Authorization code from the previous step
redirect_uri	(required) Same redirect URI which you used in the previous step
client_id	(required) Application's client ID
client_secret	(required) Application's client secret
grant_type=authorization_code	(required)

Response

After a successful request, a valid access token will be returned in the response:

{
  "user_id": "usr_uxRTYG32kbzWHxtQvfVEgwEdQdu",
  "access_token": "00a21d8b0c4e2375114e49c067dfb81eb0d2076f48354714cd5df984d87b67cc",
  "refresh_token": "81eb0d2076f48354714cd5df984d87b67cc00a21d8b0c4e2375114e49c067dfb",
  "token_type": "Bearer",
  "expires_in": 315705599,
  "scope": "workspaces:read"
}

Obtaining an access token via Client Credentials request

If the app has already been installed to a workspace, then you can obtain a token for the app user for that workspace by making a client credentials request to /oauth/token with a subject field containing the ID of the workspace.

GET https:/api.gluegroups.com/oauth/token HTTP/1.1

Pass parameters in body as URL-encoded form submission, where the Content-Type header must be application/x-www-form-urlencoded.

Parameter	Description
subject	(required) The workspace to obtain token for (ie: wks_32kbzWHxtQvfVEgwEdQduuxRTYG)
redirect_uri	(required) The registered redirect URL
client_id	(required) Application's client ID
client_secret	(required) Application's client secret
grant_type=client_credentials	(required)

Response

The token you obtain will contain all previous authorized scopes for the workspace. There is no refresh token in this case as you can simply obtain another token by repeating the request so long as the application is still installed.

{
  "user_id": "usr_uxRTYG32kbzWHxtQvfVEgwEdQdu",
  "access_token": "00a21d8b0c4e2375114e49c067dfb81eb0d2076f48354714cd5df984d87b67cc",
  "token_type": "Bearer",
  "expires_in": 315705599,
  "scope": "workspaces:read"
}

Make an API request

Once you have obtained a valid access token, you can make a request to Glue's GraphQL API. You can initialize the Glue Client with the access token:

const client = new GlueClient({ accessToken: response.access_token });
const me = await client.me;

Or pass the token as an authorization header: Authorization: Bearer <ACCESS_TOKEN>

curl https://api.gluegroups.com/public/graphql \
  -X POST \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data '{ "query": "{ me { id name } }" }' \