Flowgear OAuth

Use this feature to sign in with OAuth and obtain tokens for Flowgear.

You can use these tokens to access supported Flowgear APIs. If your goal is Core API access, continue with Core API.

OAuth Discovery Endpoints

Flowgear publishes OAuth metadata for each tenant. The following endpoints are available:

In the URLs below, replace tenantid with your tenant identifier. This is the tenant value you supply when signing in through app.flowgear.net.

Authorization server metadata: https://tenantid.flowgear.net/.well-known/oauth-authorization-server
OpenID Connect metadata: https://tenantid.flowgear.net/.well-known/openid-configuration

These metadata documents provide the OAuth endpoints for your tenant:

authorization endpoint: https://tenantid.flowgear.net/oauth2/authorize
token endpoint: https://tenantid.flowgear.net/oauth2/token
registration endpoint: https://tenantid.flowgear.net/oauth2/register
JWKS URI: https://tenantid.flowgear.net/jwks.json

If these endpoints return 404 Not Found, contact Flowgear support and confirm that OAuth access is available for your tenant.

Register an OAuth Client

Before you can sign in with OAuth, you need to register your client against the tenant. This is where you provide the redirect URI that Flowgear should use after sign-in.

Replace tenantid with your tenant subdomain and replace the sample redirect URI with your application's real callback URL.

POST https://tenantid.flowgear.net/oauth2/register
Content-Type: application/json

{
  "redirect_uris": [
    "https://app.example.com/oauth/callback"
  ],
  "client_name": "My Application"
}

Example response:

{
  "client_id": "eyJhbGciOi...",
  "client_id_issued_at": 1773750646,
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "application_type": "web",
  "redirect_uris": [
    "https://app.example.com/oauth/callback"
  ],
  "client_name": "My Application"
}

Notes:

client_id is issued by Flowgear and is required for the authorization flow.
No client secret is issued as part of registration.
In production, redirect URIs must be HTTPS.

Start the Authorization Flow

After registering the client, redirect the user to the authorization endpoint:

GET https://tenantid.flowgear.net/oauth2/authorize

The following query parameters are required:

client_id
redirect_uri
response_type=code
scope
state
code_challenge
code_challenge_method=S256

You can also provide:

nonce
resource

Example:

https://tenantid.flowgear.net/oauth2/authorize
?client_id=eyJhbGciOi...
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
&response_type=code
&scope=openid%20offline_access%20fg%3Alist%3Aservicelog%3Aglobal
&state=8f9c7b7d6a9e4b4b
&code_challenge=2YDZ1Jx0eQ8XkUj2fA8W8U9ql7oQnQm8v0qV0v7u4l4
&code_challenge_method=S256
&nonce=6d2e9d6e7e6f4b5a

After the user signs in, Flowgear redirects back to your registered redirect_uri with an authorization code.

If you want to call the Core API, include the required fg: scopes in the authorization request. For example, fg:list:servicelog:global allows access to platform logs.

Exchange the Authorization Code for Tokens

Once you have an authorization code, exchange it at the token endpoint:

POST https://tenantid.flowgear.net/oauth2/token
Content-Type: application/x-www-form-urlencoded

Form fields:

grant_type=authorization_code
client_id
code
redirect_uri
code_verifier

Example:

curl --request POST "https://tenantid.flowgear.net/oauth2/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=FLOWGEAR_CLIENT_ID_HERE" \
  --data-urlencode "code=AUTH_CODE_HERE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=CODE_VERIFIER_HERE"

Example token response:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN_HERE",
  "expires_in": 3600,
  "scope": "openid offline_access fg:list:servicelog:global",
  "id_token": "ID_TOKEN_HERE",
  "refresh_token": "REFRESH_TOKEN_HERE"
}

Notes:

Request openid if you also want an ID token.
Request offline_access if you also want a refresh token.
If your OAuth client asks for a client secret, leave it empty.

Refresh an Access Token

When the access token expires, use the refresh token grant to obtain a new access token:

curl --request POST "https://tenantid.flowgear.net/oauth2/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=REFRESH_TOKEN_HERE" \
  --data-urlencode "client_id=FLOWGEAR_CLIENT_ID_HERE"

Troubleshooting

`404 Not Found` on OAuth endpoints

If endpoints such as /.well-known/oauth-authorization-server, /oauth2/register, or /oauth2/token return 404, the tenant probably does not have OAuth access enabled.

`400 Bad Request` during authorization or token exchange

Common causes:

the redirect_uri does not exactly match a registered redirect URI
the authorization code has already been used or has expired
the code_verifier does not match the original PKCE challenge
code_challenge_method was not S256

Common causes:

the token is invalid or expired
the token was issued for a different tenant